Tuesday, December 22, 2009

BI Publisher: Bursting Designer Version 1.2

Whats new in the Bursting Designer 1.2?

Version 1.2 is here and it includes the following enhancements:
  1. Excel Output
  2. Templates tab fix. If you enter more than one template row it may have potentially caused the application to crash. Also, the templates could potentially be assigned to all the deliveries.
Whats next?

The Bursting Designer 1.3 will include enhanced printer options that are undocumented by Oracle. The following attributes will be added to the Printer delivery tab:
  1. attributes-charset
  2. attributes-natural-language
  3. document-format
  4. job-name
  5. media
  6. orientation-requested
  7. requesting-user-name
  8. sides

The Delivery Designer is also another skunk works project that I'm working on. The tentative release will be sometime in December or late January. This tool will allow a developer to test the delivery APIs without writing a lick of code. There is no need to speculate, whether or not a delivery API is capable of a particular integration point.

Ever been asked, "Can we send a document to an EDI system using as2 Document Delivery APIs?" I know I have and I really didn't have a confident answer of yes or no and I had no way of finding out without writing some code. So, the Delivery Designer will let you kick the tires so speak before making a coding commitment. You'll be able to tell your manager confidently, yes this will work!

More details to follow....

POST A QUESTION
If 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.

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
start->run
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:

http://java.sun.com/j2se/1.5.0/docs/guide/deployment/deployment-guide/jcp.html
http://java.sun.com/j2se/1.5.0/docs/guide/deployment/deployment-guide/console.html

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. http://bethwphoto.com/ike/bipublisher/ReportConversion/ReportConversion.zip/ike/bipublisher/BurstDesignerDist/launch.html

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.

Issue:
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:

codebase="http://web.me.com/beth.wiggins/ike/bipublisher/BurstDesignerDist/"

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.

Question:
Printer node not found when when bursting. Example: ipp://localhost:631/printers/${CF_PRINTER_NAME}.
Answer:
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: http://bipublisher.blogspot.com/2007/10/bi-publisher-bursting-how-to-resolve.html

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 --
[1]attributes-charset:utf-8
[1]attributes-natural-language:en
[1]printer-uri:ipp://localhost:631/printers/null
[1]document-format:application/pdf
-- printer attrs --
-- job attrs --
[1]copies:1
After adding the document key:
IPP version: 10
operation id: 02
charset: utf-8
request id: 1
-- operation attrs --
[1]attributes-charset:utf-8
[1]attributes-natural-language:en
[1]printer-uri:ipp://localhost:631/printers/HP_TEST_PRINTER
[1]document-format:application/octet-stream
-- printer attrs --
-- job attrs --
[1]copies:1

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]attributes-charset:utf-8
[1]attributes-natural-language:en
[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.

Example:
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=""
xapi:document

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

http://blogs.oracle.com/xmlpublisher/2009/12/dynamic_delivery_file_naming.html

Example:

xapi:ftp id="ftp" server="localhost" user="hidden"
password="hidden"
remote-directory="/Users/ike/Desktop/Mallika/"
remote-file="ftp_${TRX_NUMBER}_%y.%m.%d.%S" secure-ftp="false"
xapi:ftp

[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][oracle.apps.xdo.delivery.ftp.FTPDeliveryRequestHandler][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.

Tuesday, December 15, 2009

BI Publisher: Bursting Designer Version 1.0

Whats new in the Bursting Designer?

The Bursting Designer has moved out of the beta phase! Version 1.0 is here and includes the following enhancements:
  1. FTP and Secure FTP (depends on the patch level)
  2. Webdav
  3. Key support
  4. Latest Version of BIP Libraries
  5. Memory Adjustment
So if you have written a Bursting Listener to FTP files you no longer have to do that anymore. You now can FTP reports in seconds with Oracle's Bursting Engine and the Bursting Designer! A lot of developers are not aware of the fact that BI Publisher Bursting supports FTP. I can't confirm it but I think FTP is an undocumented feature for burst control files. Will have to ask Leslie Studdard from oracle if that's the case or not, she's got people and the answers.

What about Webdav? Thats another option in the Bursting Designer. Webadv is really not a utilized feature but a powerful one. A developer could use a sharepoint portal to create a report repository or pseudo reporting dashboard. I've never had the request for it but when I do I know the Bursting Designer should do the trick!

Key support is available, finally! The beta version was working off of the 5.6.2 version. Version 1.0 works off of BIP 5.6.3 (patch 6241631) . Developers don't have to rollback to old version when creating control files. Also, developers are working with the latest APIs for BI Publisher (11.5.10.2). Should be close enough for R12 developers too!

Run time memory options have also changed for the Bursting Designer. Most developers didn't experience issues with the with web start application but some did :-( The developers that had problems had out-dated hardware. If you don't have less than 256 megs of ram that is so 1999 and you need to get with the program (literally) and get a modern machine. I've changed the app to use -Xms256m -Xmx512m instead of -Xms512m -Xmx1024m. Funny story, back in 1999 I begged my father to give me some coin so I could pick up some ram to make my machine have 128 megs of ram. Back then, 128 megs was the shizzle and I was ridding high on the hog.

Future Functionality
There are some features that are still being developed below is a list:
  • XDO uri support
  • Request Removal *Manually edit the burst control file to remove a request
  • File Browsing for File Delivery and Template Fields
If you would like to request an enhancement please feel free to post a question on this blog. Also, If you would like to participate in the development of the Bursting Designer contact me via e-mail. To date I have had no developers volunteer. If you do help out, you'll be elite like a level 3 black sage*

*I went to go get a hair-cut at a salon once (it was proximity thing). The stylist told me that they had there "level 2" people on and it would cost 40.00. I'm a dude, dudes don't need a $40.00 hair cut. Anyways, I responded with "Can you ask your level 2 people to see if they can cut me a deal. I'm a level 3 black sage and I can guarantee safe passage through the mushroom forest." Needless to say the stylist did not responsed to my request. It's easy to understand why, if I were in her shoes looking a level 3 black sage I would be spooked or
maybe I would just blew a funny fuse.

Bursting Designer Download Site
*Desupported 04.22.2010 - please use the BI Publisher Toolbox.
Bursting Designer - By clicking on the download link you will be redirected to a different site. The bursting designer is java webstart application. Java 6 is required to run this application. It's recommended to bookmark this particular blog and the download site. This is because you will need to use these links every time you wish to run the Bursting Designer or find news about updates. It's technically not a requirement to use the webstart application for the java savvy developers but in doing so you will miss out on future updates and releases. It's important to note the Bursting Designer jar files will be loaded on your machine. This allows for a significant increase in performance. If you need to remove this application for some reason, go to add/remove applications.

IMPORTANT: If you have questions about the Bursting Designer or if you find a bug please post a question on this blog. If you do not post your comment on this post, I will reject your comment. I've had some complaints in recent months that it's hard to find answers on my blog because of cross post Q&A. If you e-mail me a question about the Bursting Designer be forewarned, I may ask you to post your question on this post.

Also, The source code is available for the Bursting Designer upon request. Note: You cannot sell, copyright, distribute or reproduce the software without the express written consent of Ike Wiggins.