20.4 Elements of a Distribution XML File

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 20.5, "Distribution XML File Examples" provides use cases that demonstrate the distribution XML file elements and attributes in typical scenarios.

20.4.1 destinations

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.

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:

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:

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 id="a1". The id value must always start with an alpha character.

Can also contain variable values that reference columns used in the associated report. See Section 20.3.2 for more information.

cc

string

Optional. Variable values allowed. The recipient(s) to receive a copy of the e-mail.

bcc

string

Optional. Variable values allowed. The recipient(s) to receive a blind copy of the e-mail.

from

string

Optional. Variable values allowed. The sender of the e-mail.

replyTo

string

Optional. Variable values allowed. The e-mail account where replies should be sent.

subject

string

Default: Mail Sent from &amp;Report

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 [Name of Report]

priority

highest|high|normal|low|lowest

Default:normal

The e-mail's delivery priority.

returnReceipt

true|false

Default:false

Indication of whether the reply to individual or account should be notified when the e-mail is received.

organization

string

Optional. Variable values allowed. The name of the organization distributing the e-mail, for example:

organization="Region 10 Sales"

Or

organization="&amp;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:

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:

The body element has three attributes: srcType, format, and instance, described in Table 20-3.

Table 20-3 Attributes of the body Sub-Element of mail

Attribute

Valid Values

Description

srcType

file|report|text

Default:report

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 srcType, the default is used.

format

html|htmlcss|ascii|delimiteddata

Default:html

Required when srcType is report with a format other than html, the default; otherwise format is optional. The format of the content.

instance

this|all

Default:all

Used when the foreach element is also present. With a grouped report that is burst into separate reports, instance specifies whether the groups will be broken into separate content according to each group instance (this) or all contained within the same content (all).

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

The format of the attached material, for example format="htmlcss". Required when srcType is report and the report format is other than pdf, the default; otherwise format is optional.

name

string

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 20.3.2 for more information.

srcType

file|report|text

Default:report

The source of the attachment, either a file, a report, or text.

instance

this|all

Default:all

Used when the foreach element is also present. With a grouped report that is burst into separate reports, instance specifies whether the groups will be broken into separate content according to each group instance (this) or all contained within the same content (all).

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:

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:

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:

Table 20-5 Attributes of the include Sub-Element When Used with body or attach

Attribute

Valid Values

Description

src

(path and) filename

report

headerSection

mainSection

trailerSection

Required. The source of material specified in the preceding attach, body, file, printer, or destype element.

Because the distribution XML file is called when you run a specific report, you need not specify the report's name or location in the src attribute when src="report".

(path and) filename: The preceding element must be either body or attach, with srcType=file. Provide the directory path and file name or just a file name if the file is located in a directory listed in the REPORTS_PATH environment variable.

Other values: When the preceding body or attach element specifies srcType=report, specify the entire report (report) or provide the section(s) of the report to be included in the body or to be attached (for example, headerSection,mainSection, or trailerSection).

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:

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 id="a1". The id value must always start with an alpha character.

name

string

Required. Variable values allowed. The location and filename of the destination file. Enter a directory path. Include the filename. For example:

Windows:name="d:\reports\q4sales.pdf"

UNIX:name="reports/q4sales.pdf

Can also contain variable values that reference columns used in the associated report. See Section 20.3.2 for more information.

Used when the foreach element is also present. With a grouped report that is burst into separate reports, instance specifies whether the groups will be broken into separate files according to each group instance (this) or all contained within the same file (all).

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:

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 id="a1". The id value must always start with an alpha character.

name

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 20.3.2 for more information.

copies

string

Default:1

Number of copies of each report or each report group instance to print.

instance

this|all

Default:all

Used when the foreach element is also present. With a grouped report that is burst into separate reports, instance specifies whether the groups will be broken into separate printed reports according to each group instance (this) or all contained within the same printed report (all).

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.

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:

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 id="a1". The id value must always start with an alpha character.

name

string

Required. The name of the custom destination. For example, for a fax, this might be:

name="fax"

For a portal built with Oracle Portal:

name="oraclePortal"

instance

this|all

Default:all

Used when the foreach element is also present. With a grouped report that is burst into separate reports, instance specifies whether the groups will be broken into separate destype instances according to each group instance (this) or all contained within the same destype instance (all).

For example, if you custom destination type is a fax, instance="this" would mean a separate fax for each group instance, and instance="all" would mean one fax for all groups.

20.4.10 property

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.

Scripting on this page enhances content navigation, but does not change the content in any way.