2
Bursting and Distributing a Report

Oracle9i 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 (e.g., PDF or HTML) to multiple destinations.

In this example, you will modify a simple report we've provided to burst each section 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).

About bursting and distribution

Oracle9i 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 only fetch the data once for many different formats and destinations. Using distribution also reduces your maintenance overhead because you only need 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 to others, and the entire report to an entirely different recipient list.

For more information on bursting and distribution, see Publishing Reports to the Web with Oracle9iAS Services manual located on the Oracle Technology Network (http://otn.oracle.com) and on the documentation CD provided with Oracle9iAS.

Example Scenario

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

Table 2-1 Features demonstrated in the Bursting and Distribution example

Feature	Location
Modify an existing report (or one that you created with the Report Wizard) for bursting on a section.	Section 2.2, "Set up an existing report for bursting"
Modify the XML definition file for distribution.	Section 2.3, "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.	Section 2.4, "Run the report"

2.1 Prerequisites for this example

To build the examples in this manual, you must have the example files we've provided, as well as access to the sample schema that is shipped with the Oracle9i database.

2.1.1 Example files

If you haven't already done so, you can download the files you'll need to complete this example from the Oracle Technology network (http://otn.oracle.com/products/reports) and install them on your machine.

To download and install the example files:

1. Go to the Oracle Technology Network Web site (http://otn.oracle.com/product/reports).

2. Click Getting Started with Oracle9i Reports.

3. Click Index, then find the "Bursting and Distributing a Report" example.

4. Download the file Distribution.zip into a temporary directory on your machine (e.g., "d:\temp").

5. Unzip the contents of the file, maintaining the directory structure, into an examples directory on your machine (e.g., d:\orawin90\examples).

   This zip file contains the following files:

   Table 2-2 Files necessary for building the sample report for bursting and distribution

   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 report you will distribute.
   Examples\Distribution\result\inventory_report_dist.rdf.	The report you will burst.
   Examples\Distribution\result\REP_*.pdf	The PDFs that are generated when you distribute and burst your report.

   Note: You can save the distribution.xml file we provide and reuse it later, so you don't have to create another one from scratch.

2.1.2 Access to the sample schema

If you don't know if you have access to the sample schema provided with the Oracle9i database , contact your database administrator. You should have access to the "Order Entry" portion of the schema to complete this example.

2.2 Set up an existing report for bursting

For the purposes of this chapter, we've provided you with an RDF file you can use for bursting. When you open this report, you should also connect to the sample schema in your database by choosing File > Connect. If you don't know the connection information for the "Order Entry" portion of the schema, contact your database administrator.

In this section, you will set up a repeating frame so that the data bursts on each warehouse ID. This way, you can later send the data resulting from each section as a report to each individual warehouse.

To set up a repeating frame for bursting:

1. In Reports Builder, choose File > Open.

2. 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.

3. In the Object Navigator, under the report name, double-click the Paper Layout node to display the Paper Layout view.

4. In the Paper Layout view, select the outermost repeating frame (in the Property Inspector, the name is R_G_WAREHOUSE_ID), then delete it.

Figure 2-1 Deleting the Repeating Frame

Text description of the illustration orbrdist_repfra.gif

Note: You must delete the existing repeating frame because you will modify the report to burst on each section. Later, you will distribute each section to each warehouse e-mail ID

To delete the repeating frame:

• You can select the frame in the Object Navigator:

• Under the report name, double-click the Body node to expand the list of individual layout elements.

• Under the Body node, double-click the R_G_WAREHOUSE_ID node.

• The repeating frame is selected in the Paper Layout view.

• In the Paper Layout view, delete the repeating frame.

  Tip: Do not delete the repeating from in the Object Navigator, as you will delete all the objects within the frame, as well.

For more information on frames and repeating frames, refer to the Reports Builder online help.

• In the Object Navigator, right-click the Main Section node, then choose Property Inspector.

  The Property Inspector for the Main Section displays.

• Under Section, find the Repeat On property and set it to G_WAREHOUSE_ID.

  You can set the Repeat On property by clicking the drop-down list, then selecting the item.

• Save the report as inventoryreport_dist_<your initials>.rdf.

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

2.3 Edit the distribution XML definition

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

In this section, we'll show you how to modify a distribution XML file. We've indicated locations where you need to enter your own information to make the distribution work. Note that you can save this distribution.xml file to use later, so that you don't have to manually create another file every time you want to use distribution. Our sample file also contains comments that might come in handy later.

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

• Make sure your source report (e.g., inventoryreport_dist.rdf) and your distribution XML file (e.g., 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. (We'll explain this in Section 2.4, "Run the report".)

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

For more information on distribution, see the Publishing Reports to the Web with Oracle9iAS Reports Services manual available on the Oracle Technology Network (http://otn.oracle.com).

To edit the distribution XML file:

1. In a text editor, such as Notepad, open the file we've provided called distribution.xml.

2. Find the placeholder text we've provided: <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;<city>.pdf
   
   

   Using this complete path would place the resulting PDF files in your d:\temp directory.

3. Find the placeholder text we've provided: <OriginEmailAddress>, and replace it with the sender's e-mail address.

4. Perform step 3 for all instances of the placeholder text: <OriginEmailAddress>.

5. Find the placeholder text we've provided: <DestinationEmailAddress>, and replace it with the first recipient's e-mail address.

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

   Note: For this example, we do not show you how to send multiple e-mails at once, as we do not supply built-in e-mail addresses with Reports Builder. However, if you wanted to send the report to various e-mail destinations, you would need to create a recipient field in your data model. Then, in the "ex2" section of the distribution.xml, replace the placeholder text "<DestinationEmailAddress> with "&amp;&lt;recipient&gt;". You can then delete the first section of the distribution.xml file (marked "ex1").

7. Save the XML file to the same directory where you've 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 destination of the XML file at runtime.

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.

2.4 Run the report

Since this example is a Web report, you can distribute it from either the command line or using your Web browser. For both methods, the following parameters apply:

<YourPath> is where your RDF file is located and where your distribution.xml file is located. Your login ID and Reports server name is your login information for the sample schema you've used with the sample RDF.

From the command line

Type the following text in the command line:

RWRUN REPORT=<YourPath>/inventoryreport_dist_<YourInitials> USERID=<Your Login 
ID> SERVER=<Your Server Name> DISTRIBUTE=YES 
DESTINATION=<YourPath>/distribution.xml

Using a URL

Type the following text in the Location field of your browser:

../RWSERVLET?REPORT=<YourPath>/inventoryreport_dist_<YourInitials>&USERID=<Your 
Login ID>&SERVER=<Your Server 
Name>&DISTRIBUTE=YES&DESTINATION=<YourPath>/distribution.xml 

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.

2.5 Summary

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

• Modify the layout of an existing report to burst on a section in your layout

• Distribute a report using e-mail by modifying the distribution.xml file