Saturday, December 19, 2009

BI Publisher: Troubleshooting Bursting

How to Troubleshoot the Bursting Designer & Bursting

Since the bursting designer has come out I been getting quite a few questions lately. This post tackles some common issues that most developers run into when using the Bursting Designer or using Oracles BI Publisher Bursting Engine. If you haven't used the Bursting Designer yet, go on ahead and start kickin' the tires!

Issue: Bursting Designer Web application crashes when the application is downloading. Something like this might occur, " Java 6 splash screen shows, then "Warning - Security" window blips by, then nothing."
Resolution: There can be a wide variety of reasons why this might occur. The first thing to do is make sure your an administrator or windows power user. Because your installing software you need to make sure you have the appropriate rights.

The second thing you should do is check that java 1.6 is installed.

To find out what version your running go to
type: cmd, hit return
type: java -version

If java 1.6 is installed that can be eliminated. The next step would be to verify the amount of memory you have on your machine.

By default the Bursting Designer does not support dated hardware. The minimum amount of memory required is 512 megs. If you do not have 512 megs installed on your machine the Bursting Designer will not open. In order to fix this, modify the JNLP file and replace the memory options with this line:

<j2se args="-Xms128m -Xmx256m -Xdebug" version="1.5+"/>

Then manually open the JNLP file through IE or Firefox locally on your PC. Do not try and use the download link because it will use the standard memory options. I don't advice against modifying the memory settings, but I would recommend that you talk to your hardware guy in your organization and either request a new pc or ram upgrade. It's the 21st century and you should have a computer that has 21st century power. What are we in russia? I kid for all the Russians who read my blog :-)

Now, if the Bursting Designer is still crashing. Turn on the java debugger. Go to the control panel in windows and you should see an icon for java. Double click on the app. Select the show console option in Java Control Panel in the Advanced tab. This will let you see an errors that are occurring in the application or general debug info.

See the link below and go to the debug section for the java console:

If you cannot figure-out what the errors means in the debug console, post a comment here with the error message or find my email address and I'll do my best to help resolve the issue.

Issue: JNLP downloads but doesn't open the Bursting Designer
Resolution: The JNLP file is not associated correctly in windows or it's pointed at the wrong java runtime environment.

I ran into this issue myself when I first deployed and tested the Bursting Designer in windows. That's why I set up the JNLP associations on the download page. I have instructions for most browsers and I have tested the Bursting Designer on Firefox, IE & Safari.

For IE and windows users follow these steps:

To set up the association between *.jnlp files and javaws.exe in Windows which also handles IE:
1. In Windows, not IE, click Start | Settings | Control Panel | Folder Options | File Types.
2. Check to see if there is already an association for *.jnlp files.
3. If there is no entry for *.jnlp files already then click new | advanced | select "jnlp file"
4. If there is an entry, select it and click advanced.
5. Then edit the open application used to perform action field and make sure it is set to "C:\Program Files\java\jre...\bin\javaws.exe ""%1". Uncheck DDE.
6. Click OK.
7. Click Set As Default to make Open the default action. Likely Open will be the only action.
8. Click OK | Close.

Bursting Designer crashes and the web app log file says it's pointing to this directory: file:/Users/ike/Code/NetBeansProjects/Bursting%20Designer/dist/
Resolution: Contact me, I need to fix the JNLP file. If your in a bind you can do it yourself by changing the code base node to:


Issue: Bursting Designer crashes when I click the run button.
Resolution: Follow the steps above to turn on java debug console. If you can not identify the issue or a workaround post the error on my blog or send me an e-mail. There is a known issue on the templates tab. If you enter more than one template row it may potentially cause the application to crash. This will be fixed in Bursting Designer Version 1.2.

Issue: Templates are shown across document deliveries.
Resolution: This will be fixed in Bursting Designer Version 1.2. I had a bug in my code that allowed a user to circumvent document to template associations.

Printer node not found when when bursting. Example: ipp://localhost:631/printers/${CF_PRINTER_NAME}.
1. XML is case sensitive, is the printer xml node upper case?
2. Is the printer node a child of the of the parent node selected in the xpath expression?
3. Are you using a document key? It's important, you need this to burst the file correctly. This is new for EBS users, it was not a feature in the original 5.6.3 version of BI Publisher. If you don't have a document key, it will not work.
4. Finally, it could be a pruning issue. See:

Question: How do I identify a printing issue.
Answer: Use the Bursting Designer and review the log file. In the example below we can see that the issues is related to the printer name.

IPP version: 10
operation id: 02
charset: utf-8
request id: 1
-- operation attrs --
-- printer attrs --
-- job attrs --
After adding the document key:
IPP version: 10
operation id: 02
charset: utf-8
request id: 1
-- operation attrs --
-- printer attrs --
-- job attrs --

Question: Printer not found when when bursting.
Answer: You will see a message in the logfile that looks something like this:

IPP version: 10
operation id: 46
charset: utf-8
request id: 20
-- operation attrs --
[1]status-message:The printer or class was not found.
-- printer attrs --
-- job attrs --

During upgrades sometimes printers that are setup can get wiped out. I know this true on a Mac. So the first step would be to verify the printer actually exists in the setup. If it doesn't add it. Now it's important to note, if you can't bring up the printer in your browser: http://localhost:631/printers then you may have a CUPS issue depending on how your system is setup.

Question: FTP files fail
Answer: Before starting a ftp control file, I would suggest you initial create file delivery instead. This will allow you to work out the kinks and make sure your control file is first class as well as your format template. Once you know there are no issues, then I would try setting up the FTP delivery. To troubleshoot FTP issues do the following:

1. Check the permissions. Suggest that you open a session in telnet and attempt to manually FTP. If you can't do it in telnet, you can't do it with BIP!
2. Verify the user name and password is correct. Remember it's case sensitive.
3. Verify the files are actually being generated. If there not, than obviously there is nothing to FTP. Also, verify the files aren't being generated with just an extension, in which case there is an issue with the document key.
4. Related to number 3, Verify the document key exists and is correct.

Question: Delivery Fails to show in the logfile or the delivery does not get processed.
Answer: BI Publisher Bursting Engine has some undocumented issues for multiple deliveries, below is a breakdown

1. Multiple deliveries for the same request are supported. If you assign the deliveries to one document you should be okay. See example 1.
2. Multiple distinct deliveries, that are individually assigned to a document will only process the last delivery (LIFO) in the document list. This is a very common mistake new developers make regardless if there using the Bursting Designer or not. Should you design your control file this way? No.

Example 1 is okay, Example 2 is wrong and it needs to be put in another request. The Bursting Designer application will allow you to setup a control file like example 2. Could this be a feature someday? Who knows.....Basically, if oracle allows you to do something and doesn't throw an error the Bursting Designer does the same.

Example 1: One Request - Multiple deliveries assigned to a document.
document key="${TRX_NUMBER}" output-type="pdf" delivery="ftp2, print"
Example 2: One Request - Multiple distinct deliveries assigned to a document.
document key="${TRX_NUMBER}" output-type="pdf" delivery="ftp2"

...some template assigned...
document key="${TRX_NUMBER}" output-type="pdf" delivery="print"
...some template assigned...

Also, putting a filter on each template will not resolve the issue with example 2. You will still have the same issue. Word of advice, when in doubt just create two requests and you use the template filters.

Question: Can there be multiple templates assigned for a delivery?
Answer: Yes. If a filter does not exist, all templates will be applied to the output. When all templates are applied to the output file it will occur in LIFO order.

xapi:document key="${TRX_NUMBER}" output-type="pdf" delivery="file"
xapi:template type="rtf"location="/Users/temp.rtf" filter=""
xapi:template type="rtf"location="/Users/temp2.rtf" filter=""

Template temp2.rtf will be applied first, and then temp.rtf. Also, there will only be one output file. I do not know if this desired functionality by Oracle or not, so you can use this at your own risk.

Question: Are document keys required for all document elements?
Answer: Absolutely, if a key node is left blank or doesn't exist your requested delivery may process but no results will be generated.

Question: Is there an alternative to creating template filters
Answer: Predicates are allowed for request xpath expressions. Now, don't think that because they are you can start getting fancy. There are very limited.

Is it better or worse than a template filter? No, the two are the same. Personally, I think it's easier to understand by having it in the request itself.
Question: Is CSV supported for bursting?
Answer: Yes, you will need to use etext templates.
Question: Is xdo:// uri syntax supported for Bursting?
Answer: Yes.
Question: Is xdo:// uri syntax supported for Bursting Designer?
Answer: No.Jan-15-2010: XDO Protocol is supported in the Bursting Designer

Question: I want to use bursting as a way to apply one or multiple format templates indiscriminately to the output file and I only want a single file(s) to be generated, I actually don't want it bursted.
Answer: Seems like an oxymoron, but it's really not. You may very well run into this situation, I know I have. In your request, just use slash "/" and for the key field generate a something in the data template that is below the root node and use that. As an example, lets say user requested that they need have 3 separate csv files. You could create 3 etext and burst the xml file. Make sense?
Question: I want to use excel as an output format in the Bursting Designer
Answer: That will be available in version 1.1 of the application.
Question: Are Data Expressions supported in Bursting?
Answer: Absolutely. It's supported for e-mail, ftp and webdav. Bursting uses the delivery manager APIs so by default that functionality works for bursting. For more info data expressions see Tim D. blog


xapi:ftp id="ftp" server="localhost" user="hidden"
remote-file="ftp_${TRX_NUMBER}_%y.%m.%d.%S" secure-ftp="false"

[ASYNC_TIMEOUT:Integer] [86400000]
[HOST:String] [localhost]
[RETRY:Integer] [0]
[ASYNC_CHECK_INTERVAL:Integer] [60000]
[TEMP_FILE_SUFFIX:String] [.tmp]
[USERNAME:String] [hidden]
[PASSWORD:String] [*******]
[TEMP_FILE_PREFIX:String] [dlvr]
[FTP_REMOTE_DIRECTORY:String] [/Users/ike/Desktop/Mallika/]
[FTP_REMOTE_FILENAME:String] [ftp_1537394_%y.%m.%d.%S]
[RETRY_INTERVAL:Integer] [60000]

[121909_020451288][][STATEMENT] submitRequest(): Opening connection : [localhost][21][hidden][****][/Users/ike/Desktop/Mallika/][ftp_1537384_2009.12.19.51][true]

Question: Is xdodelivery.cfg supported for Bursting?
Answer: Although, I have never tried it, I suspect it is. If you do try it let me know.
Jan-15-2010: xdodelivery.cfg is supported
Question: Is xdodelivery.cfg supported for the Bursting Designer?
Answer: No. If I ever decide to support it, I will create a property on the properties tab.Jan-15-2010: xdodelivery.cfg is supported in the Bursting Designer

Question: Does Bursting support custom delivery channels?
Answer: No. Would it be possible for oracle to do this? Absolutely, but not many organizations need this functionality.

POST A QUESTIONIf you have questions about the Bursting Designer or if you find a bug please post a question on this blog. Please no cross posting and make sure the question matches the topic.


Ganesh said...

I follow your blog regularly. I am using the BI Publisher Toolbox and is very helpful.

We are on R12.1 EBS. Can I set the file read and write permission for the files using bursting control file? If not, how does the output file generated by bursting gets its permission in unix? Is it based on umask of the unix user?

Ike Wiggins said...

No, you cannot do that.

You could use the delivery manager api's to change file permission.

Have you tried the Bursting Designer?

Suvarna said...

Hi there

I have a report that im bursting to the file system. When i use an output type of RTF, everything works well. WHen i use PDF as the output type, i get a Document Generation Failed error (Error rendering document). I looked in the log file and nothing seems out of the ordinary. When i open the .out file generated in Adobe Reader (on my local machine), it opens successfully and shows the correct information.

WHen i look at the job details, i can see that it splits the report correctly.

I am on BI Publisher and the template is an RTF.

Please if there are any tips you can give me, i would appreciate that. I have searched extensively and not found anything that helps me to fix this. Im about to pull my hair out!!

Thanks very much!

Ike Wiggins said...

Not all of the documents may have been rendered correctly. I would suggest taking the xml file and running it locally in msword to see if you can generate pdf for ALL of the data.

Other than that I don't have any really good answers for you. You download the BI Publisher Toolbox (which is on this site) and test the file with the bursting designer

Suvarna said...

i can generate a pdf from the template successfully in Word, so the data is ok. I will try Toolbox and see if can help me, but thanks for your answer at least - ive posted in like 65 million places and this is the first answer i have received.


Anonymous said...

Hi,I have a question, we are using a bursting file to send our checks to the printer, after all the checks print there is an additional blank page with 2 lines on the top containing the xml code from the bursting file. Do you know what would be causing this to print out on a separate page (or why it's printing out at all) and how we can stop it from doing this?

Ike Wiggins said...

No, bursting doesn't cause extra page breaks. You probably have an extra carriage return somewhere or the table is set to carry over to the next page. You should make the cells fixed for checks and do not allow it to break to another page.