37 Bursting and Distributing a Report

Oracle Reports enables you to deliver a single report to multiple destinations simultaneously. By taking advantage of this feature, you can create a single report, then send it in any format (for example, PDF or HTML) to multiple destinations.

In this example, you will modify a simple report we have provided to burst each group to a separate report. You will then modify a sample distribution XML file to send an e-mail to each destination with an attachment based on the separate reports. You will also send multiple e-mails to the same e-mail address with a single attachment (the entire report).

Concepts

Oracle Reports enables you to deliver a single report to multiple destinations simultaneously. Using the new, enhanced distribution feature, you can set up your report to be distributed to an e-mail destination, a portal, a printer, or anywhere else when the report is run. This feature also enables you to improve performance, since you fetch the data only once for many different formats and destinations. Using distribution also reduces your maintenance overhead because you need only one job request to publish the report to multiple destinations. You can refine this further by sending the Header section to some recipients, the Main section to others, and the entire report to an entirely different recipient list.

For more information on bursting and distribution, see the Oracle Application Server Reports Services Publishing Reports to the Web manual, available on the Oracle Technology Network Oracle Reports Documentation page () and on the documentation CD provided with Oracle Application Server.

Example Scenario

In this example, you are the report developer for a manufacturing company who needs to deliver monthly information to its warehouses. You will modify an existing report to burst on each warehouse ID, creating separate PDF reports for each warehouse. You will then edit the distribution XML file we have provided to e-mail each report as an attachment to the corresponding warehouses.

As you build this example report, you will:

Set up an existing report for bursting on a warehouse group.
Edit the distribution XML definition.
Run the report to PDF format so that the report is e-mailed to the destinations defined in the distribution.xml file.

To see a sample distribution report, open the examples folder named Distribution, then open source\inventory_report_dist.rdf for report you will distribute, or result\inventory_report_dist.rdf for the report you will burst. For details on how to open these reports, see "Accessing the Example Reports" in the Preface. The example files used in this chapter are listed and described in Table 37-1.

Table 37-1 Example report files

File	Description
`Examples\Distribution\source\distribution.xml`	The XML file that controls the distribution properties for your report.
`Examples\Distribution\source\inventory_report_dist.rdf`	The source report you will modify to burst and distribute.
`Examples\Distribution\result\inventory_report_dist.rdf`	The modified report you will burst and distribute.
`Examples\Distribution\result\REP_*.pdf`	The PDFs that are generated when you distribute and burst your report.

Note:

The distribution.xml file we have provided for this example is specific to building this example report. A more comprehensive distribution.xml is shipped with Oracle Reports in the ORACLE_HOME\samples\demo directory; you can reuse this file for your own purposes so that you do not have to create one from scratch.

37.1 Prerequisites for this example

To build the example in this chapter, you must have the example files we have provided (see "Example Scenario", above), as well as access to the Order Entry sample schema provided with the Oracle Database. If you do not know if you have access to this sample schema, contact your database administrator.

37.2 Set up an existing report for bursting

For the purposes of this chapter, we have provided an RDF file you can use for bursting. In this section, you will set up the report for bursting by deleting the repeating frame and setting the Repeat On property of the Main section, so that the data bursts on each warehouse ID. This way, you can distribute the data for each warehouse as a report to the corresponding warehouse e-mail ID.

Note:

For more information on the Repeat On property, refer the Oracle Reports online Help.

To set up the report for bursting:

In Reports Builder, choose File > Open.
Navigate to the directory where your examples source files are located, and open the file inventory_report_dist.rdf.

The report displays in the Object Navigator.
In the Object Navigator, under the report name, double-click the view icon next to the Paper Layout node to display the Paper Layout view.
In the Paper Layout view, select the outermost repeating frame (R_G_WAREHOUSE_ID), then delete it.

Figure 37-1 Deleting the repeating frame

Description of "Figure 37-1 Deleting the repeating frame"

See Also:
For more information on frames and repeating frames, refer the Oracle Reports online Help.
In the Object Navigator, right-click the Main Section node, then choose Property Inspector to display the Property Inspector for the Main Section:
- Under Section, set the Repeat On property to G_WAREHOUSE_ID.
Save the report as inventoryreport_dist_your_initials.rdf.

You have set up your report to burst based on the warehouse ID.

37.3 Edit the distribution XML definition

The Oracle Reports distribution XML file enables you to specify the details of your distribution. For example, if you are distributing through e-mail, you can specify such details as the addressee, the reply to address, and the subject.

In this section, you will learn how to modify a distribution XML file. We have indicated locations where you need to enter your own information to make the distribution work.

When you want to distribute a report, you need to either:

Make sure your source report (for example, inventoryreport_dist.rdf) and your distribution XML file (for example, distribution.xml) are in the same directory.

OR
When you run the report from the Reports Server, set the destination to the path of the XML file. (This is explained in Section 37.4, "Run the report".)

We have provided both these files in a single directory: Examples/Distribution/source/.

Note:

For more information on distribution, see the chapter "Creating Advanced Distributions" in the Oracle Application Server Reports Services Publishing Reports to the Web manual, available on the Oracle Technology Network Oracle Reports Documentation page (http://www.oracle.com/technology/documentation/reports.html).

To edit the distribution XML file:

In a text editor, such as Notepad, open the sample distribution.xml file we have provided.
Find the placeholder text: <YourFilePath>, and replace it with the location of where your resulting PDFs will be stored.

Example: Replacing the placeholder text with:
```
d:\temp\
```
changes the path to:
```
d:\temp\Rep_%amp;&lt;city&gt;.pdf
```
Using this complete path places the resulting PDF files in d:\temp.
Find the placeholder text: <OriginEmailAddress>, and replace it with the sender's e-mail address.
Perform step 3 for all instances of the placeholder text: <OriginEmailAddress>.
Find the placeholder text: <DestinationEmailAddress>, and replace it with the recipient's e-mail address.

Perform step 5 for all instances of the placeholder text: <DestinationEmailAddress>.

Note:

For this example, we show you how to send e-mails to static e-mail addresses. However, if you want to send the report to various e-mail destinations, you must create a recipient field in your data model. Then, in the ex2 section of distribution.xml, replace the placeholder text <DestinationEmailAddress> with &<recipient>. You can then delete the first section of the distribution.xml file (marked ex1).

Save the XML file to the same directory where you have saved inventoryreport_dist_your_initials.rdf.

Note:

It is not required that you save the XML file to the same directory where your RDF is located, as you can specify the location of the XML file at runtime. Either distribution.xml and RDF must be in Reports Path, or provide the complete path in the command line URL.

You have finished customizing the distribution XML file to send a single e-mail to corporate headquarters with all of the individual warehouse reports, and multiple e-mails with a single attachment each to the individual warehouses.

37.4 Run the report

You can distribute the report using a Web browser. Type the following command in the Location field of your browser:

http://host:port/reports/rwservlet?REPORT=your_path/inventory_report_dist_your_
initials.rdf&USERID=your_login_ID&SERVER=your_server_name&DISTRIBUTE=YES&
DESTINATION=your_path/distribution.xml

where

your_path is where your RDF file and the distribution.xml file is located. your_login_ID is your login information for the sample schema you have used with the sample RDF.

The SMTP mail server is set up during the installation process. If you did not specify a server during installation, you can set up the mail server manually before distributing your report to an e-mail destination. You can specify the outgoing mail server using pluginParam in the server config file.

EXAMPLE:
<pluginParam name="mailServer">smtp01.mycorp.com</pluginParam>

For more information on setting up the mail server, refer to the chapter "Configuring Oracle Reports Services" in the Oracle Application Server Reports Services Publishing Reports to the Web manual, available on the Oracle Technology Network Oracle Reports Documentation page ().

Running the report creates a file for each warehouse based on the warehouse ID in the specified directory. When the report is distributed, a single e-mail is sent to one address with all of these files attached to the e-mail.

If you set up the distribution.xml file for multiple e-mail addresses, each warehouse (or each e-mail address) would be sent a single e-mail with a single attachment file that includes the report for that warehouse.

37.5 Summary

Congratulations! You have distributed a report. You now know how to:

modify the layout of an existing report to burst on a group in your layout.
distribute a report using e-mail by modifying the distribution.xml file.

For more information on any of the wizards, views, or properties used in this example, refer to the Oracle Reports online Help, which is available in Reports Builder or hosted on the Oracle Technology Network (OTN), as described in Section 3.1.1, "Using the Oracle Reports online Help".