Oracle XML Publisher - by Dinesh Kumar S
Oracle XML Publisher - by Dinesh Kumar S
Contents
Topic
Page No.
10
BI Publisher Architecture
19
22
51
81
Template Features
101
XML Bursting
127
References
What is in Name?
Current Name
Old Name
Oracle BI Publisher
XML Publisher
Template Builder
Oracle Reports Builder is the report-building component of Oracle Reports, a powerful enterprise
reporting tool that enables you to rapidly develop and deploy sophisticated Web and paper reports
against any data source.
Leveraging Java EE technologies such as JSP and XML, you can publish your reports in a variety of
formats (including HTML, XML, PDF, spreadsheet, delimited text, PostScript, and RTF) to any
destination (including e-mail, Web browser, Oracle Portal, and file system) in a scalable, efficient
manner.
In Oracle Reports, a single executable RDF file contains the data source, layout, business logic, and
the language-specific prompts.
Report File
Data Logic
Layout
Translation
Multiple language:
Global implementations for a large organization usually require the same report to be
developed in multiple languages. In case of Oracle Reports, developers will have to
create different copies of the same RDF files and place them in the <application
top>/reports/<language> directory.
In case of any bug fixes to data or any changes to layout, all the copies of reports have
to be amended.
Trivial tasks:
Even trivial tasks like changing the prompt or minor changes to the layout require a
developer in Oracle Reports.
Using BI Publisher, these tasks can be implemented by trained support staff or business
analysts.
Distribution:
The distribution capabilities in the Oracle Reports tool within E-Business Suite are very
restrictive. To distribute the output of Oracle Reports, many companies implementing
E-Business Suite have to purchase third-party products or even build their own inhouse reports distribution framework.
With BI Publisher, a mechanism named bursting can automate distribution of the
reports using industry standard delivery protocols.
10
Data Logic
Report Output
Layout
Translation
11
12
2. Many Source
Oracle Bi Publisher consists of One or More Sources that feed a template created by
any supported method. The resulting output can be sent/distributed to one or more
destinations.
Oracle XML Publisher - by Dinesh Kumar S
13
14
4. Report Bursting
15
5. Distributed Delivery
16
17
18
BI Publisher Architecture
19
BI Publisher Architecture
20
Data handler
Template Manager
Document Processor
Translation Handler
Delivery Server
21
22
Generate XML
Upload Template
23
24
External Sources
(DWH, MDX Query, Web Services,
LDAP, Oracle Discoverer)
Upload Template
Internal Sources
(Oracle Apps)
Conc. Pg
PL/SQL
Reports
Conc. Pg RDF
Reports
Data Template
etc..
25
Internal Sources
Conc. Pg PL/SQL
Reports
1.1) Choose a Co u e t p og a
Conc. Pg RDF
Reports
Data Template
at as XML .
1.2) When program Successfully completed open the output in browser and
save it in .XML file.
26
Application
Receivables
Report Name
Step 1.1
27
In the Requests window, search for your Job ID and check the status of the job. If the job is
completed, click the View Output button.
View the report in a browser. Because no template is associated with the report and you have
requested an XML output, the report is an XML file. Save the XML file as customer.xml in your local
drive.
Step 1.2
28
29
We can use the BI Publisher Template Builder, which is an Addin to Microsoft Word, to build an RTF template.
Upload Template
30
31
Select Data > Load XML Data from the BI Publisher menu.
32
Step 2.3:
Preview the data
33
34
Generate XML
Upload Template
To publish your report, you must register the data source that
would be merged with the template.
When you register your layout template file (in the next
section), you must assign to it a data definition that exists in the
Template Manager. This associates the two at run time.
Note** multiple templates can use the same data definition.
35
Step 3.1) Log in to E-Business Suite and click XML Publisher Administrator.
36
Step 3.2) Click the Data Definitions link and you will be on the Data Definition tab for XML
Publisher. Click the Create Data Definition button to create a new data definition.
37
Step 3.3) Under Create Data Definition, fill the form as shown below. It is critical that you use
the correct short name of the Concurrent Program - ARXCOBLX to correctly link this data
definition to the underlying Concurrent Program and Oracle Reports report. For the Name
field, you can use whatever you like. Click Apply.
38
Step 3.4) You should see a confirmation message. Now you have successfully created the
data definition for the Customer Balance Letter.
39
40
Upload Template
41
Step 4.2) Enter the template name as Customer Balance Letter - Template.
Select Application name as Receivables using the Lookup icon. Enter code as ARXCOBLX.
Click the Lookup icon next to the Data Definition field, enter cust%, and then click Go.
Select the Customer Balance Data definition option from the list and click Select.
42
Step 4.3) Select the template type as RTF from the Type drop-down list. Remember, you
had saved your template as an RTF file.
43
Step 4.4) You now need to upload the template that you created in Microsoft Word. To
select the template file you created, scroll down to the Template File section. For File,
browse and open the file called Balance Letter - Template.rtf.
44
Step 4.6) Click Apply. You should get a message that your template has been created
successfully.
45
46
Generate XML
Upload Template
47
Note that in the Layout field, the layout template file is listed. Click the Options button
to see the other options that you can set after the report is completed.
48
The Upon Completion.. window appears. In this window, you can specify what actions can
be taken after the job is executed. You can notify one or more people about the report. You
can send the report to be printed. Click OK.
49
In the Requests window, search for your Job ID and check the status. If the job is completed,
click the View Output button.
50
51
Note** Developers generally use an Oracle reports (or) PL/SQL program to generate XML.
52
Logical Flow
The data template is the method by which you communicate your request for data to
the data engine.
It is an XML document whose elements collectively define how the data engine will
process the template to generate the XML.
53
Parameter
Data
Template
Triggers
Data
Structures
4
Oracle XML Publisher - by Dinesh Kumar S
54
Before understanding the Data Template components lets understand simple PL/SQL
procedure, which generates tabular report.
1. Creating Procedure with Parameters
3. Condition is triggered
55
56
Element
Description
Data Template
Property
Section
Required?
Yes
Optional
Data Query
Section
Data Trigger
Optional
In the data structure section you define what the XML output
will be and how it will be structured.
The complete group hierarchy is available for output.
It is required for multiple queries and optional for single
queries.
If omitted for a single query, the data engine will generate flat
XML.
Yes Multiple
Query
Data Structure
Yes
Optional
Single Query
57
Required?
name
description
version
defaultPackage
if data template contains lexical references or any other calls Yes if lexical is
used
to PL/SQL.
dataSourceRef
Yes
Optional
Yes
Yes
58
Attribute Name
name
Description
A keyword, unique within a given Data Template, that identifies the
parameter.
Specify the parameter data type as "character", "date", or "number".
Default value is "character".
Required?
Yes
defaultValue
This value will be used for the parameter, if no other value is supplied
from the data at runtime.
Optional
include_in_output
Optional
dataType
Optional
59
Attribute Name
Description
name
60
Attribute Name
Description
name
source
The location of the trigger indicate at what point the trigger fires:
Place a beforeReport trigger anywhere in your data template before the
<dataStructure> section. A beforeRepot trigger fires before the dataQuery is
executed.
Place an afterReport trigger after the <dataStructure> section. An afterReport trigger
fires after you exit and after XML output has been generated.
61
In the data structure section you define what the XML output will be and how it
will be structured. The complete group hierarchy is available for output.
62
63
64
65
Exercise
66
67
This Data Template selects the product details from the demo_products table.
It uses a bind parameter to find the product name against the product code.
For each bind parameter in the query , we need to define a Parameter in the
Concurrent Program
Oracle XML Publisher - by Dinesh Kumar S
68
Navigation: XML Publisher Administrator -> Data Definitions -> Create Data Definition
69
70
71
72
Note**
1. Output format should be XML
2. Short Name in the concurrent program and Code in the data definition
should be same.
Oracle XML Publisher - by Dinesh Kumar S
73
Note:
Token is p_product_id. This is the bind parameter we have used in date template. For every bind
parameter used in the
dataXML
template,
we
have
to define
74
Oracle
Publisher
- by
Dinesh
Kumar Sparameter in the concurrent program.
75
Execute the concurrent program "Product Demo epo t and click on the Output
button get the Data XML.
Save the XML file to generate the RTF Template.
Note:
We are getting the output in xml because we did t define template &
associated yet.
76
77
Using the Table Wizard as below to create the 'Table Report Format' with the
columns of demo_products.
78
79
To maximize performance when building data queries in the data template: XML
Publisher tests have shown that using bind variables is more efficient than using the
link tag.
The data Structure section is required for multiple queries and optional for single
queries. If omitted for a single query, the data engine will generate flat XML.
80
Creating Placeholders
Defining Groups
Defining Headers & Footers
Inserting Images
81
Creating Placeholders
The placeholder maps the template field to the XML element data field.
At runtime the placeholder is replaced by the value of the element of the same name
in the XML data file.
There are two ways to insert placeholders in your document:
1. Basic RTF Method: Insert the placeholder syntax directly into your template
document.
2. Form Field Method: (Requires Microsoft Word) Insert the placeholder syntax in
Microsoft Word's Text Form Field Options window. This method allows you to
maintain the appearance of your template.
82
83
84
Double-click the form field area to invoke the Text Form Field Options dialog box.
85
Select OK to apply.
86
he figure below shows the Supplier field from the template with the added form field
markup.
87
88
Following is the XML file that will be used as input to the Payables Invoice Register report
template:
89
The Placeholder Entry is the XML element tag name entered in the Form Field Help
Text field
Invoice Num
1234566
<?INVOICE_NUM?>
Invoice Date
1-Jan-2004
<?INVOICE_DATE?>
GL Date
1-Jan-2004
<?GL_DATE?>
Curr
USD
<?INVOICE_CURRENCY_CODE?>
Entered Amt
1000.00
<?ENT_AMT?>
Accounted Amt
1000.00
<?ACCTD_AMT?>
<?ENT_SUM_VENDOR?>
<?ACCTD_SUM_VENDOR?>
1000.00
90
91
Defining Groups
By defining a group, you are notifying BI Publisher that for each occurrence of an
element, you want the included fields displayed.
At runtime, BI Publisher will loop through the occurrences of the element and display
the fields each time.
In the example, for each occurrence of G_VENDOR_NAME in the XML file, we want the
template to display its child elements,
o VENDOR_NAME (Supplier Name)
o G_INVOICE_NUM (the Invoices group)
o Total Entered Amount
o Total Accounted Amount.
And, for each occurrence of G_INVOICE_NUM (Invoices group), we want the template to
display Invoice Number, Invoice Date, GL Date, Currency, Entered Amount, and Accounted
Amount.
92
To designate a group of repeating fields, insert the grouping tags around the elements to
repeat.
Syntax:
<?for-each:XML group element tag name?>
<?end for-each?>
Now Lets use the same XML data to create the report.
93
Following is the XML file that will be used as input to the Payables Invoice Register report
template:
94
95
96
97
98
99
Inserting Images
BI Publisher supports several methods for including images in your published document:
1. Direct Insertion: Insert the jpg, gif, or png image directly in your template.
2. URL Reference: In Microsoft Word's Format Picture dialog box select
the Web tab. Enter the following syntax in the Alternative text region to reference
the image URL.
url:{'http://image location'}
100
Template Features
101
Page Breaks
To create a page break after the occurrence of a specific element use the "split-bypage-break" alias.
This will cause the report output to insert a hard page break between every
instance of a specific element.
Note: Page breaks are supported for PDF, RTF, and PPT output. Page breaks are not
supported for HTML output.
Syntax:
<?split-by-page-break:?>
102
<?split-by-page-break:?>
103
<?initial-page-number:pagenumber?>
BI Publisher also supports continuing the page number from a previous section.
The default behavior of a new section in a document is to reset the page
numbering. However, if your report requires that the page numbering continue
into the next section, use the following command:
<?initial-page-number:'auto'?>
104
105
Summary Information to be
printed at last page of the report.
106
The report should show each VENDOR and their INVOICE data with a SUMMARY section that
appears only on the last page, placed at the bottom of the page.
Insert a Microsoft Word section break (type: next page) on the first page of the template. For the
final page, insert new line characters to position the summary table at the bottom of the page.
The summary table is shown in the following figure:
107
Conditional Formatting
108
The conditional formatting that you specify can be XSL or XSL:FO code, or you can
specify actual RTF objects such as a table or data
For example,
you can specify that if reported numbers reach a certain threshold, they will
display shaded in red.
you can use this feature to hide table columns or rows depending on the
incoming XML data.
109
IF Statements
Use an if statement to define a simple condition; for example, if a data field is a
specific value.
Syntax:
110
For example, to set up the Payables Invoice Register to display invoices only when the
Supplier name is "Company A .
111
If-then-Else Statements
This is extremely useful when you need to test a condition and conditionally show a
result.
Use the following syntax to construct an if-then-else statement in your RTF template:
<? xdofx: if element_condition then result1 else result2 end if ?>
For example, the following statement tests the AMOUNT element value.
If Amount > 1000 then
"Higher";
Else if < 1000 then
"Lower";
Else
"E ual ;
End if;
112
Choose Statements
Use the choose, when, and otherwise elements to express multiple conditional
tests.
If certain conditions are met in the incoming XML data then specific sections of
the template will be rendered.
Use the following syntax for these elements:
113
114
Default Text Entry in Example Form Field Help Text Entry in Form Field
<Grp:VAT
<?for-each:G_VAT?>
starts the G_VAT group
<Choose
<?choose:?>
opens the choose statement
<When EXEMPT_FLAG='^'
<?when: EXEMPT_FLAG='^'?>
tests the EXEMPT_FLAG element, if true, use the first table
shown
End When>
<?end when?>
ends the EXEMPT_FLAG test
<Whe POTED_FLAG= *
<? he :POTED_FLAG= * ?>
tests the POSTED_FLAG element, if true, use the table
following
End When>
<?end when?>
ends the POSTED_FLAG test
Otherwise
<?otherwise:?>
If none of above are true then use the following table
End Otherwise>
End Choose>
End Vat>
<?end otherwise?>
ends the otherwise statement
<?end choose?>
ends the choose statement
<?end for-each?>
ends the G_VAT group
Oracle XML Publisher - by Dinesh Kumar S
115
Cell highlighting
116
Report Template:
117
Description
Opens the for each-loop for the element
account.
The placeholder for the number element
from the XML file.
1-232-4444
<?number?>
CH1
<?if:debit>1000?><xsl:attribute
xdofo:ctx="block" name="backgroundcolor">red</xsl:attribute><?end if?>
100.00
<?debit?>
CH2
<?if:credit>1000?><xsl:attribute
xdofo:ctx="block" name="backgroundcolor">red</xsl:attribute><?end if?>
100.00
<?credit?>
EFE
<?end for-each?>
118
Report Output:
119
120
Syntax:
<?add-page-total:TotalFieldName;'element'?>
TotalFieldName
element
121
<?show-page-total:TotalFieldName;'Oracle-number-format'?>
Oracle-number-format format you wish to use to for the display, using the
Oracle format mask (for example: C9G999D00).
The example shows how to set up page total fields in a template to display total
credits and debits that have displayed on the page, and then calculate the net
of the two fields.
122
Template Layout
Description
This field defines the opening "for-each" loop for the transaction
group.
100.00
<?debit?><?add-page-total:dt;'debit'?>
This field is the placeholder for the debit element from the XML
file. Because we want to total this field by page, the page total
declaration syntax is added. The variable defined to hold the
total for the debit element is dt.
90.00
<?credit?> <?add-page-total:ct;'credit'?> This field is the placeholder for the credit element from the XML
file. Because we want to total this field by page, the page total
declaration syntax is added. The variable defined to hold the
total for the credit element is ct.
Net
<add-page-total:net;'debit - credit'?>
Creates a net page total by subtracting the credit values from the
debit values.
EFE
<?end for-each?>
123
Report Output:
124
Data Handling
125
Sorting
You can sort a group by any element within the group.
Syntax:
For Example;
Sorting a Group:
<?for-each:G_VENDOR_NAME?> <?sort:VENDOR_NAME?>
Sorting Multiple Fields:
<?sort:VENDOR_NAME?> <?sort:INVOICE_NUM;'ascending';'number'?>
126
XML Bursting
127
About Bursting
Bursting is a process of splitting data into blocks, generating documents for each
block, and delivering the documents to one or more destinations.
The data for the report is generated by executing a query once and then splitting the
data based on a "Key" value.
For each block of the data, a separate document is generated and delivered.
Example implementations include:
128
Bursting Mechanism:
Oracle Bursting Mechanism enables us to deliver a single XML Publisher report/letter
to multiple destinations simultaneously.
One can create a single report/letter , then send it in any format (e.g., PDF or HTML) to
multiple destinations(email ids).
There are two kind of bursting mechanism available within BI publisher
1. Control File Base:- Integrated with EBS.
2. Delivery SQL based:o Part of Enterprise release.
o All delivery, template, output format, locale and other details define through
delivery SQL Query.
o Enterprise Edition assume that this information is stored in data base. The
process create the XML file out if this query and the delivery xml file works as
control file.
129
130
131
132
133
134
Step 1.4) Attach the concurrent program to the request group and execute the program to
generate the XML output.
135
136
137
138
139
140
XML tag
Explanation
xapi:request select=
xapi:delivery
xapi:email
141
xapi:message
142
xapi:document This node contains the attachment document and XML template
related tags and attributesThe attributes in this tag are related to the email attachment
Key or unique identifier of each attachment
Output or attachment file name
Output-type or attachment file type
143
144
The following attributes should contain the same values for bursting to function
properly,
1.
2.
3.
If the 3 values do not match then delivery will not take place as expected.
145
146
A temporary directory has to be provided for XML Publisher engine to use for bursting.
Navigation: XML Publisher Administrator Administration Tab
147
We are dropping the template file in this location, as the location in the
bursting control file is given as,
<xapi:template type=rtf location=/usr/tmp/XXEMPDET.rtf />
148
149
After the report is generated, execute the program named, XML Publisher
Report Bursting Program.
This program is responsible for bursting the XML with the help of the bursting
control file attached to the concurrent program whose output will be burst.
Note**
Ensure that this program is attached to the request group of this responsibility.
150
The bursting program output shows that 4 emails were delivered. Lets check
the mail box.
151
152
Thank You
(Please rate my article in www.planet-source-code.com)
153