Oracle® Fusion Middleware Publishing Reports to the Web with Oracle Reports Services 11g Release 1 (11.1.1) B32121-01 |
|
![]() Previous |
![]() Next |
The elements of a distribution XML file include:
Most of these elements have attributes that define the behavior of the element. The following sections describe the distribution XML file elements and their associated attributes. Section 19.5, "Distribution XML File Examples" provides use cases that demonstrate the distribution XML file elements and attributes in typical scenarios.
Example
<destinations>
one or more distribution specifications
</destinations>
Required/Optional
Required. You must have no more or less than one destinations
element in your distribution XML file.
Description
The destinations
element opens and closes the content area of the distribution XML file. In terms of the distribution XML file's tagging hierarchy, all the other elements are subordinate to the destinations
element.
Example
<foreach> <mail id="a1" to="my_addressee@mycompany.com" subject="Fourth Quarter Results"> <attach format="pdf" name="dept_&<department_ID>.pdf' srcType="report" instance="this"> <include src="mainSection"/> </attach> </mail> </foreach>
or
<mail id="a4" to="recipient@mycompany.com" subject="Regional Results"> <foreach> <attach format="pdf" name="report.pdf" srcType="report" instance="all"> <include src="mainSection"/> </attach> </foreach> </mail>
Required/Optional
Optional. You can have as many foreach
elements as you require.
Description
Use the foreach
element to burst your distribution against a repeating group. You can use foreach
only when the associated report definition file (either RDF, JSP, or XML) has its Repeat On property for the section that will be burst set to an appropriate group. The foreach
element specifies that the distribution defined between its open and close tags should be performed for each repeating group.
The Repeat On property can be set for a report section (Header, Main, and Trailer) to associate a data model break group to a section. By setting the Repeat On property for a section, you can generate multiple instances of a section, or a repeating section.
When you implement bursting and distribution in a report, you can generate section-level distribution by setting the Repeat On property for a section to a data model break group, which generates an instance of the section for each column record of that break group. Then, you can distribute each instance of the section as appropriate (for example, to individual managers in the MANAGER
group).
If you set the Repeat On property for more than one of the Header, Main, and Trailer sections of a report, all Repeat On property values must be set to the same data model break group. If the Repeat On property for any one of the Header, Main, and Trailer sections is set to a different data model break group, Oracle Reports raises the following messages:
REP-177: Error while running in remote server REP-34320: Report sections used in destination '<destination id>' do not repeat on the same group
You can also use the foreach
element as a sub-element of the mail element, as depicted in the second example provided at the start of this section. (In this example, assuming that mainSection
repeats on G_DEPARTMENT_ID
, the example will produce a single attachment with all the instances of the report's mainSection in a single file.)
The foreach
element works closely with the instance
attribute of the attach and file elements. While foreach
specifies that the distribution should be performed according to record groups, instance
specifies whether the burst groups should be distributed in one file (instance="all"
) or distributed as separate files: one file for each group instance (instance="this"
).
When used with the mail
element, foreach
can mean different things according to its position relative to the mail
element:
When foreach
precedes the mail
element and instance="this"
, each group instance is dispatched as a separate mail. For example:
<foreach> <mail id="a1" to="managers@mycompany.com" subject="results"> <attach name="department_&<department_id>.pdf" instance="this"> <include src="mainSection" /> </attach> </mail> </foreach>
If the report is grouped according to department_id
, and there are four departments, then there are four group instances. This means four e-mails per recipient, each e-mail with its own group instance attached: one e-mail has department 10's report attached; another e-mail has department 20's report attached; and so on. Each recipient receives all four e-mails.
When foreach
follows the mail element and instance="this"
, each group instance is attached to one e-mail going to each recipient. For example:
<mail id="a1" to="managers@mycompany.com" subject="results"> <foreach> <attach name="department_&<department_id>.pdf" instance="this"> <include src="mainSection" /> </attach> </foreach> </mail>
Example
<mail id="a1" to="jsmith@foo.com" subject="Results"> <body srcType="text"> Attached are quarterly results. </body> <attach srcType="report"> <include src="headerSection"/> <include src="mainSection"/> </attach> </mail>
or
<mail id="a4" to="recipient@mycompany.com" subject="Regional Results"> <foreach> <attach format="pdf" name="report.pdf" srcType="report" instance="this"> <include src="mainSection"/> </attach> </foreach> </mail>
Required/Optional
Optional. You can have as many mail
elements as you require.
Description
Use the mail
element to specify distributions through an outgoing SMTP-based mail server. Use it to specify the recipients, the subject, and the priority of the e-mail.
Between an open and close tag of the mail
element, there can be only one body
sub-element and anywhere from zero to multiple attach
and foreach
sub-elements.
The mail
element also has a set of related attributes. These are expressed within the mail
tag. For example, the id
, to
, and subject
attributes are expressed:
<mail id="a1" to="jsmith@foo.com" subject="Recent Hires">
Table 19-2 lists and describes the attributes of the mail
element.
Table 19-2 Attributes of the mail Element
Attribute | Valid Values | Description |
---|---|---|
string |
Required. A keyword, unique within a given distribution XML file, that identifies a particular mail element. This can be a combination of a text string and one or more numbers, for example |
|
string |
Required. Variable values allowed. The recipient(s) of the e-mail. Contains the full, formal e-mail address, for example:
Multiple recipients must be separated with commas. Can also contain variable values that reference columns used in the associated report. See Section 19.3.2 for more information. |
|
string |
Optional. Variable values allowed. The recipient(s) to receive a copy of the e-mail. |
|
string |
Optional. Variable values allowed. The recipient(s) to receive a blind copy of the e-mail. |
|
string |
Optional. Variable values allowed. The sender of the e-mail. |
|
string |
Optional. Variable values allowed. The e-mail account where replies should be sent. |
|
string |
Default: Mail Sent from Optional. Variable values allowed. The subject of the e-mail. In the absence of a specified subject, the subject line will read: Mail Sent from [ |
|
|
Default: The e-mail's delivery priority. |
|
|
Default: Indication of whether the replyto individual or account should be notified when the e-mail is received. |
|
string |
Optional. Variable values allowed. The name of the organization distributing the e-mail, for example: organization="Region 10 Sales" Or organization="&department_name" |
Note: For the mail element to work properly, the Reports Server must know which outgoing SMTP mail server to send mail to. You specify this information in the Reports Server configuration file (rwserver .conf ). This file has a pluginParam element where you can enter the name of a mail server. For example:
<pluginParam name="mailServer" value="%MAILSERVER%"> <property name="enableSSL" value="yes"/> </pluginParam> For more information, see Chapter 7, "Configuring Oracle Reports Services". |
Example
On Windows
<mail id="a1" to="jsmith@foo.com" subject="Results"> <body srcType="file"> <include src="c:\mail\body.html"/> </body> </mail>
On UNIX
<mail id="a1" to="jsmith@foo.com" subject="Results"> <body srcType="file"> <include src="/mail/body.html"/> </body> </mail>
Required/Optional
Optional. You can have a maximum of one body element associated with a given mail element.
Description
The body
element acts as a sub-element to the mail
element. It specifies the content (or body
) of the e-mail. With body
, you can type a text string between the open and close tags of the body
element or use an include sub-element to specify either an external file, a report, or a section of a report. For example:
<mail id="a1" to="jsmith@foo.com" subject="Results"> <body srcType="text"> Attached are quarterly results. </body> …
or
<mail id="a1" to="jsmith@foo.com" subject="Results"> <body srcType="file"> <include src="d:/reports/admin/results.html"/> </body> …
or
<mail id="a1" to="&<first_name>.&<last_name>@myco.com" subject="Quarterly Results"> <body srcType="report" format="html"> <include src="headerSection"/> </body> …
The body
element has three attributes: srcType
, format
, and instance
, described in Table 19-3.
Table 19-3 Attributes of the body Sub-Element of mail
Attribute | Valid Values | Description |
---|---|---|
|
Default: The source for content of an e-mail. The content is displayed in the body of the e-mail. In the absence of a specified |
|
|
Default: Required when |
|
|
Default: Used when the foreach element is also present. With a grouped report that is burst into separate reports, |
Example
<mail id="a1" to="jsmith@foo.com" subject="Results"> <body srcType="text"> Attached are quarterly results. </body> <foreach> <attach format="html" name="contacts.htm" srcType="report" instance="all"> <include src="headerSection"/> <include src="mainSection"/> </attach> </foreach> </mail>
or
<mail id="DEST1" to="tsmith@oracle.com" subject="Mail from dest" > <attach srcType="report" format="delimiteddata" name="myattach.txt" <include src="report"/> </attach> </mail>
Required/Optional
Optional. You can have as many attach
elements as you require with a mail
element. Note that attach
is also a sub-element of foreach, and foreach
requires that at least one of its sub-elements be used (out of mail,file,printer,destype,
and attach
).
Description
The attach
element specifies attachments to the e-mail. Additionally, attach
must have at least one include sub-element, and can have more than one if srcType="report"
.
Table 19-4 lists and describes the attributes of the attach
element.
Table 19-4 Attributes of the attach Sub-Element of mail
Attribute | Valid Values | Description |
---|---|---|
|
Default: The format of the attached material, for example |
|
|
Optional. Variable values allowed. The filename of the attached material. Can also contain variable values that reference columns used in the associated report. See Section 19.3.2 for more information. |
|
|
Default: The source of the attachment, either a file, a report, or text. |
|
|
Default: Used when the foreach element is also present. With a grouped report that is burst into separate reports, |
Using these attributes in conjunction with the foreach element, you can design a destination that will repeat on a group instance and generate an e-mail for each group attachment. For example:
<foreach> <mail id="a2" to="first.name@myco.com,second.name@myco.com, third.name@myco.com, fourth.name@myco.com" subject="Department Summaries"> <body srcType="text"> Attached is the breakdown of department summaries for the last quarter. </body> <attach format="htmlcss" name="deptsum.html" srcType="report" instance="this"> <include src="report"/> </attach> </mail> </foreach>
By moving the location of the foreach
element, you can generate one e-mail with multiple attachments: a separate one for each group instance.
<mail id="a2" to="first.name@myco.com,second.name@myco.com, third.name@myco.com, fourth.name@myco.com" subject="Department Summaries"> <body srcType="text"> Attached is the breakdown of department summaries for the last quarter. </body> <foreach> <attach format="htmlcss" name="deptsum.html" srcType="report" instance="this"> <include src="report"/> </attach> </foreach> </mail>
Example
<mail id="a1" to="jsmith@foo.com" subject="Q4"> <body srcType="text"> Attached are quarterly results. </body> <attach srcType="report" format="pdf"> <include src="report"/> </attach> </mail>
or
<mail id="a1" to="jsmith@foo.com" subject="Q4"> <body srcType="text"> Attached are quarterly results. </body> <attach srcType="report" format="htmlcss"> <include src="headerSection"/> </attach> </mail>
or
<mail id="a1" to="jsmith@foo.com" subject="Q4"> <body srcType="text"> Attached are quarterly results. </body> <attach srcType="file"> <include src="d:/management/reports/current/Q4.htm"/> </attach> </mail>
Required/Optional
Required when used with body
and attach
when srcType
is report
or file
, but not when srcType
is text
. Also required for file
, printer
, and destype
. In the instances where it is required, you must have one and can have more than one include
.
Description
The include
element is available for use with the body, attach, file, printer, and destype elements. It specifies the file, report, or report section to be included in the body of an e-mail, as an attachment to an e-mail, in the content of a file, in the printer output, or in the content of a custom destination type.
If you want to specify more than one section, but not the entire report, enter an include
for each required section. For example:
<mail id="a1" to="jsmith@foo.com" subject="Results"> <body srcType="text"> Attached are quarterly results. </body> <attach srcType="report" format="htmlcss"> <include src="headerSection"/> <include src="mainSection"/> </attach> </mail>
If the preceding body
or attach
element has srcType
of file
, the subsequent include
can specify the file either with a directory path and filename or with just the filename, provided the file is located in a directory listed in the REPORTS_PATH
environment variable. For example:
<mail id="a1" to="jsmith@foo.com"> <body srcType="file"> <include src="q4sales.pdf"/> </body> </mail>
If you do specify a path, use the appropriate standard for your platform. For example:
On Windows:
<include src="c:\management\reports\current\Q4.htm"/>
On UNIX:
<include src="/management/reports/current/Q4.htm"/>
No other XML elements are placed between an include
element's open and close tag.
Table 19-5 describes the src
attribute of the include
element.
Table 19-5 Attributes of the include Sub-Element When Used with body or attach
Attribute | Valid Values | Description |
---|---|---|
|
Required. The source of material specified in the preceding Because the distribution XML file is called when you run a specific report, there is no need to specify the report's name or location in the
Other values: When the preceding |
Example
On Windows
<file id="a7" name="c:\management\reports\report.pdf" format="pdf"> <include src="report"/> </file>
or
<file id="MyFiles2" name="c:\My_Departments_Report.txt" format="delimiteddata"> <include src="report"/> </file>
On UNIX
<file id="a7" name="/management/reports/report.pdf" format="pdf"> <include src="report"/> </file>
or
<file id="MyFiles2" name="/My_Departments_Report.txt" format="delimiteddata"> <include src="report"/> </file>
On Windows or UNIX
<foreach> <file id="a7" name="section&<department_id>.pdf" format="pdf" instance="this"> <include src="mainSection"/> </file> </foreach>
Required/Optional
Optional. You can have as many file
elements as you require.
Description
Use the file
element to specify distributions to a file. The file
element has one sub-element: include. There must be at least one include
sub-element and there may be more between an open and close tag of the file
element.
When used with the foreach element and the instance="this"
attribute, the file
element can distribute each group instance of a grouped report to separate files. For example, if you group a report on department_id
, and there are four departments, you can use the foreach
/file
/instance="this"
combination to generate four files, each with a separate department's report. In this case, the file
entry in the distribution XML file might look like this:
<foreach> <file id="a3" name="dept_&<department_id>.pdf" format="pdf" instance="this"> <include src="report"/> </file> </foreach>
In this example, all report sections (header, main, and trailer) must repeat on the same group instance (for example, department_id
).
Table 19-6 lists and describes the attributes of the file
element.
Table 19-6 Attributes of the file Element
Attribute | Valid Values | Description |
---|---|---|
string |
Required. A keyword, unique within a given distribution XML file, that identifies a particular file element. This can be a combination of a text string and one or more numbers, for example |
|
string |
Required. Variable values allowed. The location and filename of the destination file. Enter a directory path. Include the filename. For example: Windows: UNIX: Can also contain variable values that reference columns used in the associated report. See Section 19.3.2 for more information. |
|
|
Default: The destination file format. For example:
|
|
|
Default: Used when the foreach element is also present. With a grouped report that is burst into separate reports, |
Example
On Windows
<printer id="a1" name="\\server_name\printer_name" copies="5"> <include src="report"/> </printer>
On UNIX
<printer id="a1" name="alias_to_registered_printer" copies="5" instance="all"> <include src="report"/> </printer>
Required/Optional
Optional. You can have as many printer
elements as you require.
Description
Use the printer
element to specify distributions to a printer. The printer
element has one sub-element: include. There must be at least one include
sub-element and there may be more between the open and close tags of the printer
element.
When used with the foreach element and the instance="this"
attribute, the printer
element can distribute each group instance of a grouped report to a separate print job. For example, if you group a report on department_id
, and there are four departments, you can use the foreach
/printer
/instance="this"
combination to generate four printed reports, each containing a separate department's report. In this case, the printer
entry in the distribution XML file might look like this:
<foreach> <printer id="a7" name="\\server_name\printer_name" instance="this"> <include src="report"/> </printer> </foreach>
In this example, all report sections (header, main, and trailer) must repeat on the same group instance (for example, department_id
).
Table 19-7 lists and describes the attributes of the printer
element.
Table 19-7 Attributes of the printer Element
Attribute | Valid Values | Description |
---|---|---|
string |
Required. A keyword, unique within a given distribution XML file, that identifies a particular file element. This can be a combination of a text string and one or more numbers, for example |
|
string |
Required. Variable values allowed. The destination printer. How you enter this information differs between Windows and UNIX. For Windows, specify the printer server name and the printer name. For example: name="\\server_name\printer_name" For UNIX, specify the alias assigned to a registered printer. For example: name="sales_printer" Can also contain variable values that reference columns used in the associated report. See Section 19.3.2 for more information. |
|
string |
Default: Number of copies of each report or each report group instance to print. |
|
|
Default: Used when the foreach element is also present. With a grouped report that is burst into separate reports, |
Example
<destype id="acustom1" name="fax"> <include src="headerSection"/> <property name="number" value="914925551212"/> </destype>
See Section 19.5, "Distribution XML File Examples" for examples of using the destype
element in a distribution XML file to specify distribution to the following destinations: Oracle Portal, FTP, WebDAV, and fax.
Required/Optional
Optional. You can have as many destype
elements as you require.
Description
Use the destype
element to specify distribution to a custom destination, such as a fax machine or an FTP site. You also use destype
to specify distribution to a portal created with Oracle Portal. The destype
element allows for the use of two sub-elements: property and include. At least one include
is required.
Note: The inclusion of a custom destination type requires that you have a defined distribution handler in place to push report content to the custom output destination. Build a custom destination type through the Oracle Reports Services Destinations API.For more information on the available APIs for Oracle Reports, refer to the Reports Software Development Kit (RSDK) on the Oracle Technology Network (OTN): on the Oracle Reports page ( |
When used with the foreach element and the instance="this"
attribute, the destype
element can distribute each group instance of a grouped report to a separate destype
instance (for example, a separate fax). For example, if you group a report on department_id
, and there are four departments, you can generate four destype
instances, each containing a separate department's report. In this case, the destype
entry in the distribution XML file might look like this:
<foreach> <destype id="a9" name="fax" instance="this"> <include src="report"/> <property name="number" value="&<fax_number>"/> </destype> </foreach>
In this example, all report sections (header, main, and trailer) must repeat on the same group instance (for example, fax_number
).
Custom destination types also have a set of related attributes. These are expressed within the destype
tag. For example, the id
, name
, and instance
attributes are expressed:
<foreach>
<destype id="a1" name="name_of_destination_type" instance="all">
<include src='report'/>
</destype>
</foreach>
Table 19-8 lists and describes the attributes of the destype
element.
Table 19-8 Attributes of the destype Element
Attribute | Valid Values | Description |
---|---|---|
string |
Required. A keyword, unique within a given distribution XML file, that identifies a particular file element. This can be a combination of a text string and one or more numbers, for example |
|
string |
Required. The name of the custom destination. For example, for a fax, this might be:
For a portal built with Oracle Portal:
|
|
|
Default: Used when the foreach element is also present. With a grouped report that is burst into separate reports, For example, if you custom destination type is a fax, |
Example
<foreach> <destype id="custom1" name="fax" instance="all"> <include src="headerSection"/> <property name="number" value="914925551212"/> </destype> </foreach>
Required/Optional
Optional. You can have as many properties as you require under a destype
element.
Description
The property
element allows for the inclusion of name/value pairs expressed in terms recognized by a custom destination type (destype). Properties are merely passed along to the destination handler. They serve no function within Oracle Reports Services. How you specify properties is entirely dependent on the requirements of your custom destination.