36
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 (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

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 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 Oracle Application Server Reports Services Publishing Reports to the Web manual located on the Oracle Technology Network (http://otn.oracle.com) and on the documentation CD provided with OracleAS.

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 36-1 Features demonstrated in this example

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

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

36.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/products/reports).

2. Click Getting Started with Oracle 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 36-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.

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

36.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 view icon next to the Paper Layout node to display the Paper Layout view.

4. In the Paper Layout view, select the outermost repeating frame (R_G_WAREHOUSE_ID), then delete it.

   Tip: You can select the R_G_WAREHOUSE_ID in the Object Navigator to simultaneously select it in the Paper Layout view, where you can delete it. Do not delete the repeating frame in the Object Navigator, as you will delete all the objects within the frame, as well.

Figure 36-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

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 to display the Property Inspector for the Main Section:

• Under Section, set the Repeat On property and 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.

36.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'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 36.4, "Run the report".)

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

For more information on distribution, see the Oracle Application Server Reports Services Publishing Reports to the Web 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.

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

• Perform step 3 for all instances of the placeholder text: <Origine-mailAddress>.

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

• Perform step 5 for all instances of the placeholder text: <Destinatione-mailAddress>.

  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 <Destinatione-mailAddress> with &amp;&lt;recipient&gt;. You can then delete the first section of the distribution.xml file (marked ex1).

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

  36.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 on the command line:

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

  Usage notes

  • In the above command line, the parameter "SERVER=<Your Server Name>" is optional. If you do not specify a server name, Oracle Reports will use the default server.

  • 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 email destination. You 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, Release 10g (9.0.4).

  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.

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

  For more information on any of the wizards, views, or properties used in this example, refer to the Reports Builder Online Help, which you can access in two ways:

  • From the Oracle Technology Network (http://otn.oracle.com/products/reports/), click Documentation and navigate to the Reports Builder Online Help for the most recent, hosted online help.

  • From Reports Builder, choose Help > Help Contents.

    Note: You can replace your Reports Builder online help with the most recent update by downloading the latest online help set available on the Oracle Technology Network (http://otn.oracle.com/docs/products/reports/). Instructions for replacing your help file are included in the readme.txt in the download file.