The BIP Puzzle

I've been getting a lot of questions about how many different BIP components there are to create 1 report. This question comes at a good time, seeing that we are ready to discuss working in the Apps. The answer is that you will have 5 BIP components to make up 1 report.
You will have :
1. The Data Source or Data Template (.xml file or .rdf)
2. The Concurrent Program
3. The Data Definition
4. The Template Definition
5. The Template (.rtf or .pdf file)

The Data Source
The data source is an .rdf report or .xml report. For right now we are still going to use the .rdf report to pull all of the data from the database that we need. So, in the concurrent program you will keep it set up to run the executable for your .rdf. You can also write your report in XML language and retrieve data from the database just as the .rdf does, but we will take a look at that later on.

The Concurrent Program
Because we are going to use the .rdf file as our data source, the only change that has to be made to the concurrent program is to change the output format type to XML.







By doing this, the output from your .rdf report will be in XML format. You will no longer see your .rdf layout, but you will see XML tags. This can be a little confusing because it is not the actual XML code that got the data from the database, but the output from your .rdf report. This output is what you should save as .xml and load into the template builder tool in MS Word for use in your template design.

The Data Definition
The data definition is in the Apps under the XML Publisher Administrator responsibility. The data definition is linked to the concurrent program by the concurrent program shortname. You create a new Data Definition by clicking on the 'Create Data Definition' button. You can then enter any name you would like for your report (I like to keep it the same as the concurrent program name). In the Code box, you enter the concurrent program short name. In the Application box, you enter whatever module your report is in (ex. payables). If you wrote your report in XML rather than using the .rdf, this is also where you would attach your .xml file, by clicking on the Data Template - Add File button on the bottom half of the screen.

But again, we'll step through that at a later date. Also, you must create the data definition before you create the template definition.

The Template Definition
The template definition is used to link the data layer (data definition/concurrent program) with the presentation layer (.rtf/.pdf template). You can access the Template Definition screen under the XML Publisher Administrator responsibility, just like you accessed the Data Definition screen. There is also a tab on the top of the data definition screen that you can use if you're already in there.

You can create a new template definition by clicking the create template button. On the template screen you can enter any name you want (again, I would use the concurrent program name or at least the data definition name to keep everything organized). The code is the shortname from the concurrent program and you should find the data definition for report in the LOV. The application would be the same as the application you entered in the data definition. The type would either be .rtf for the template created in MS Word of .pdf if you created one in Adobe.

The Template
The last piece of the puzzle is the template, which we have already discussed. The template is attached through the template definition screen by navigating to the template file upload section ...

You simply browse to your template file and select a language.

And there you have it... the 5 pieces needed to generate your report. Once you have set all of this up, when you run the concurrent program and view the output you should see your template and data merged together.

A Different Header on Page 2?

So you got your subtemplate working in the header of your reports, but what if you want a different header on page 2? You're in luck because that can be accomplished fairly easily.
For this example I modified the .xml file to include a notes field and a report name field. You can download the file from http://www.mediafire.com/?9xzyfy3bivd

I also created a new header/footer subtemplate and an example3.rtf template. They are also available for download at : http://www.mediafire.com/?8vb1vmteoay and http://www.mediafire.com/?1dxwodzd7mz .

Let's first look at the new header/footer subtemplate:

In the subtemplate header I am now passing 2 parameters (P_DATE and REPORT_NAME). I added REPORT_NAME so that for our examples at least, the name of the report will be dynamic. Then, in the middle column I called the value passed to the subtemple for REPORT_NAME by using <?REPORT_NAME?>. Now onto the new example3.rtf template

The template has a few changes that we can see (as indicated by the arrows). First, the value of REPORT_NAME from the .xml file is being passed to the subtemplate in our header by using ;$REPORT_NAME;$REPORT_NAME. The second change is in the main table indicated by arrow 2. The only change here, was that I added a second row to display our new vendor notes tag from the example3.xml file. The last change shown in the image above is the addition of the template 'BodyHeader' that will be used on pages other than the first page.

Back to the main topic of this post.... MS Word functionality gives us the ability to have a different first page. If you enter the header section of the template (View -> Header and Footer) you will see this icon

This has a properties dialog box where you can set 'different first page'.

When you click 'OK' you will be back out to your header section of the template. Enter what you would like for the header and footer (in our case, it is the call to ex3_subtemplate.rtf). Once you set this up on the first page, go to the end of your template layout and insert a page break. On the new blank page 2, go back to the header and footer section and enter what you would like on page 2. If you downloaded the example3.rtf file, you may not see page 2 because if I left blank lines in the template the output was showing an extra page. But, if you hit enter until you get to page 2, you will see different code in the header section.

This is the call to the template that we have in our example3.rtf. It is not a subtemplate that is used universally, but a subtemplate used within example 3. Because you are not allowed to enter tags in the header and footer sections of the .rtf, a call to a subtemplate will accomplish this. And here is our final product....

Happy BIPping!

What Are Subtemplates?

Using Subtemplates

I found a fantastic way to make our lives as BIP developers a lot easier! It's called the subtemplate and it can be used over and over again. For example, if your company has a logo that they like to display on every report header, you can create a subtemplate that holds the image. Then, when you create the report template you call the subtemplate and your header logo is loaded into your report template. The same goes for report footers. If your company likes to display their name and address in the footer, you create another subtemplate with that information and call is in the footer of your report template. Everyone likes to find shortcuts, right? Well this shortcut could save you time and also make your reports more consistent because when you re-create the header for every report there is more room for error.

Another great thing about using subtemplates is that if you have to make a change to the company logo or address, you only have to make the change in one place and it shows on every report! Now, if you've already created templates without using subtemplates, I'm not trying to be a trouble maker and say to go back in and change them all.... but you should really convert over to this method for your next report. It will pay off in the long run!

So how do you use these things? You can create subtemplates by using XSL or XSLT (a transformation languages used with XML data for formatting) or you can create an .rtf document like we did in our last 2 examples. I found using an .rtf file is pretty straight forward in MS Word and it's also great for inserting a logo. You can still use XSL to format the data like we did in example1a for setting a default value, so don't worry about that.

Here is a short subtemplate example for ya....

First off, I modified the .xml file from example1a to add a date tag which will be used in our report header. You can download the new .xml file from http://www.mediafire.com/?0ce5ajbljmd
Next is our new subtemplate file that includes our company header and date that is an element name from our report output.

You can also download this from http://www.mediafire.com/?0ezjdthomyn . In this .rtf file we have our header and footer data as indicated by <?template:Header?> and <?template:Footer?>. Within those tags I created tables that are the same width as the report where I would like to add the header/footer. There is also a parameter tag <?param@begin:P_DATE?> . This tag creates a parameter that is used in the Header to display the date from the report data.

Lastly, we have our example2.rtf file where we call the subtemplate http://www.mediafire.com/?533dqzmjtjt




In MS Word, this is what is in the header. You are calling the 'header template' from the subtemplate and passing the value P_DATE from the .xml file to the subtemplate.

To link the report template with the subtemplate you have to import the subtemplate file in the report template body with the below syntax :
<?import:file:/// [path] subtemplate_file.rtf?>

You call the footer subtemplate the same way that you called the header subtemplate. As long as your header and footer are in the same .rtf file, you would only have to import the file one time in your report template body. Seeing that we aren't displaying and report data in the footer there are no parameters like in the header, but you could certainly add that if you so desire

So there you have it, our first look at using subtemplates.. enjoy!
Feel free to leave me comments and let me know if you found this helpful - BIPgirl

Enhancing your Layout

Hopefully everyone had a chance to look at example1. Well now, I would like to change it. I had a comment on my blog about handling null values, so I thought I would address that in today's post. I have created example1a.xml to demonstrate how to handle a null phone number value and put a default value in it's place. You can then take the logic in the template and apply it wherever you need to.

Here is example1a.xml (you can download it from http://www.mediafire.com/?5qnnju1zg1i )

But first I have to step back a second and explain a little more about our template file. For example1a, I took the .rtf file from example1 and enhanced it. You can download this template from http://www.mediafire.com/?9ocfbtmtzlp







From our previous example I have added a title, vendor phone column and combined the address, city, state and zip fields into one column. I have also removed the table borders using normal MS Word functionality to make the data look more 'report-like' rather than "table-like".

What I didn't discuss in our first example is that each field that was entered through our template-builder table/form menu has a "text form field options" box. If you double-click on VENDOR_PHONE you will get a box that looks like this :

We have a lot of formatting and conditional options using this little option box!
If you click on the 'Add Help Text' button in the lower left hand corner you will
normally just see the XML tag from your data.xml file. This is how the XML data
is merged with the template.

So... I bet you're wondering how you enter a default value if our phone number just happens to be null. Am I right? In the same Text Form Field Options box, we can enter
<?if:VENDOR_PHONE=''?>Private Number<?end if?>
<?if:VENDOR_PHONE!=''?><?VENDOR_PHONE?><?end if?>

Just a note, you'll want to leave out any unnecessary white space when entering into this box because you are only allowed 138 characters.

When we run our example from the Previewer as PDF we will get the output below with our default value populated for BIPboy

Our First Example

Here is a very simple example of XML code that you can copy into notepad and save as example1.xml

<?xml version="1.0"?>
<!-- Generated by Oracle Reports version 6.0.8.25.0 -->
<EXAMPLE1>
<LIST_G_MAIN_SELECT>
<G_MAIN_SELECT>
<VENDOR_NAME>BIPgirl</VENDOR_NAME>
<VENDOR_ID>00001</VENDOR_ID>
<VENDOR_LINE>1 BIPgirl Lane </VENDOR_LINE>
<VENDOR_CITY>Albany</VENDOR_CITY>
<VENDOR_STATE>NY</VENDOR_STATE>
</G_MAIN_SELECT>
</LIST_G_MAIN_SELECT>
</EXAMPLE1>

Once saved, in MS Word you go to your newly added toolbar and load the file. Select Load XML Data and then browse to example1.xml

You will get a message acknowledging that the data was loaded successfully. Then.. let the development begin!

For my first practice template, I went to the Insert Menu on the Template Builder toolbar and selected the Table/Form option. This is a quick and easy way to get the fields from your data file into your template with the correct syntax. If you select the top node from the data source pane and drag it to the template pane, you can drop all the nodes or selected ones. For this example I will just drop all the nodes and not touch any settings.

Your template will look like this :

Well that's fine and dandy, what will my user see? Another great feature of the XML Publisher Desktop Plug-in is that you can preview your output without loading it into the Apps. You must first save your template as Example1.rtf and then you can navigate back to our handy toolbar. You will see a Preview Menu on it.

This preview menu gives you 4 options for your output (PDF, HTML, EXCEL or RTF). Because my output in the Apps will be PDF, that is what I will choose to preview in.

Here is our first report!

Woo hoo! It may not look pretty, but we merged the data layer with the presentation layer on our desktop and after all, that is our goal here. In my next post I will show you how we can add our own personal touches to the output. Go ahead and give it a try!

Getting Started with BIP

I’m sure the first thing you are asking yourself is “What is BI Publisher?”. Well…. BI Publisher is a template based publishing tool that is bundled up in the Oracle EBS (there is also a stand-alone version if you do not have the EBS). BI Publisher uses desktop word processing tools for your presentation file and merges it with the EBS data. The basic idea behind this publishing tool, is to separate the presentation and data layers.

EBS holds the collection of data ->You create the presentation template ->
EBS merges the two together at runtime

The first thing that you need to do to get started with BIP is to install the desktop plug-in for MS Word. You can also develop templates in Adobe Acrobat Professional, but I have found that MS Word is the way to go. The MS Word plug-in is called Template Builder and is available on Metalink through Patch 5887917 “Oracle XML Publisher Desktop 5.6.3”

Installing the XML Publisher Desktop Plug-in for Word

After you follow the on screen installation prompts, you will see a new menu in MS Word called “Oracle BI Publisher”. You will also want to add the Template Builder Toolbar by navigating to
View > Toolbars>Template Builder. You will then see it appear with your other toolbars

From this toolbar you will load your sample XML file to add fields to the template and preview your output.

I’ll let you poke around a little.