Readers of this blog or the CF-Talk mailing list over the past couple of weeks may have noticed I’ve been having some angst about a project which used the ColdFusion Report Builder for some quite complex reports. One of my tasks was to create a final report which conditionally packaged up some of the other reports as sub-reports, with the addition of some cover pages, summaries and definitions. There was also some reformatting and addition of the company’s branding to the nine existing reports.

Over the course of this exercise some quite disturbing facts about the Report Builder came to light. Rather than just bash the product (which is quite tempting) I’ll focus here on tips for helping you to work with it, should you ever have to.

Just a note: the problems listed here were reproduced on two of my own machines, and in some cases the machine of a colleague and a dev server as well, all with vastly differing setups – so these are, to my mind, fairly well-confirmed bugs, not one-offs caused by one particularly quirky configuration. It’s also worth noting that this is using the latest version of the Report Builder available to date, build 118586.

File Overwrite Bug

First and most annoying is the bug which occurs when more than one document has been open: save a report, and it will randomly rename the file to the name of one that has also been open in the same session. The unlucky overwritten document doesn’t even need to be open at the same time. To illustrate, imagine this: open “a.cfr”, then close. Open b.cfr. Make a change to “b.cfr” and hit save. The filename magically changes to “a.cfr” and that file is overwritten. This occurred for me about half the time when working with multiple files. Closing the report builder down between document editing sessions did not help.

Working around this bug was fortunately simple, although a bit annoying: use Save As instead of Save. I took to incrementing a number in the filename – Report1.cfr became Report2.cfr became Report3.cfr, etc. Right now, my working directory has 146 versions of the same file. At least there’s an incremental record of every change made. This had a secondary benefit with working around the next bug: the 100% CPU usage bug.

But first, one quirk of the Report Builder that may not be immediately obvious – you can’t rename a .cfr file outside of the Report Builder, and then preview it from within the Report Builder. This is because the path to the current file is stored as an editable property of the report – if you rename the file using Save As, the property is updated, but if the filename is changed outside of the program, you’ll need to update that property as well (it’s a property of the top level of the report).

100% CPU Usage

Technically, this bug is not a Report Builder bug, it’s a ColdFusion or JRUN bug. It works like this: make a small change to a report and preview (PDF format). JRUN hits 100% CPU usage. I could find no rhyme or reason with this bug – and see above, this is with 146 separate versions of one file to test with. I’d make a simple change – increasing a top margin width and a left margin width, for example. Preview, JRUN hits the ceiling and stays there. After ending processes and restarting services, I go back to my previous version of the file, and make one of the changes – just the top margin, for example. Preview: success! Next, make second change (in this example, left margin width). Preview: voila, success again. Final file is identical in every conceivable way to original file which caused JRUN to panic; it just went through two iterations to get there instead of one. Sometimes it was changing an item’s property that caused the CPU to spike, and the fix would be to remove the item, save and preview, then add it again with the new property value instead of the old.

Whatever the bug was caused by, the safest way to avoid it was to make a small change, note the file number and what was changed, save and preview. If the CPU jumped up to 100% for more than about 20 seconds, kill the process, restart it, and go back to the last working version of the file. Make the change in a different way if possible and repeat. It only took me 146 goes to get it right. In fact I stopped using the remote development server like I usually do and installed ColdFusion locally on my machine, just because remote service restarts quickly got tedious.

Nested Sub-Reports Cause Report Builder to crash

My mother-of-all-reports consisted of a cover page, summary, two pages of definitions, four standard sub-reports, one to four optional sub-reports, and a big fat legal disclaimer at the end. Of the eight sub-reports, only one consisted of other sub-reports (six sub-sub-reports, in this case).

The Report Builder documentation states somewhere that nested sub-reports are supported in the engine, but only one level will display in the Report Builder itself. The reality is that nested sub-reports work fine, except if you’re trying to work with the top level report in the Report Builder. Any kind of scrolling around the document causes access violations, and too much scrolling causes the access violations to stack up until you can’t close the report builder because you can’t close the error messages fast enough, which is a bunch of fun. The only way out then is to end the process through the task manager and start over.

To work around this bug I added the sub-report containing other sub-reports and previewed immediately (without moving around the document) – and after confirming it was working, removed the problem report until the very last minute when the report was otherwise complete. This meant the process was completed with only three or four access violations being thrown. I wouldn’t want to work with multiple sub-reports – luckily there was only one in this instance.

The mysterious HTML Formatted Text property

The latest build of the Report Builder included a new property for text objects – HTML Formatted Text (true or false). It’s not in the program help or in the livedocs. Basic HTML that I tried – paragraphs, Hx elements and strong elements – didn’t seem to work – the markup showed in the rendered report. Through a process of trial and error, I discovered that <b> elements do work. Other presentation-style HTML such as the <i> element probably also work.

Random Report Builder crashes

The instance of access violation errors and sudden spontaneous program quits were quite high, and seemed to increase with the length of time that the program was open. Report Builder averaged around two to three inexplicable crashes per hour of use for the three days I worked with it. Frequent restarts are a good idea.

Here’s another fun one: in order to get my summary pages and sub-reports with page breaks in the right spots, I mis-used the group feature without a group variable to create sections. This worked quite nicely. To start with, I couldn’t remember the proper names of all my sub-reports so I labeled the groups 1, 2, 3, 4 and 5. As the sub-reports went in, I renamed the groups to be more descriptive. When group “5” was changed to its real name, “Analysis”, the Report Builder decided to change every property that had a 5 in it in the report to say “Analysis” too. The sub-report stopped showing up because Report Builder started looking for a file called ReportAnalysis.cfr instead of Report5.cfr. The default parameter being passed into the report changed from “58” to “Analysis8”. Anything that should have been “5” changed to the string “Analysis” throughout the report. Why not hey? I can’t even begin to explain that one!

Another one: don’t try to be clever and specify a negative margin value. As my sub-reports were designed to be standalone reports as well, they had their own margins. These margins were being added to the margins of the parent report, causing all sorts of formatting problems. There doesn’t seem to be a way to specify different margins for different pages/groups/sections, and one of my experiments was to try to specify a negative margin – however this just resulted in an error dialog that couldn’t be exited (the report builder process had to be terminated from the Task Manager). As for the margin issue itself, the creation of two versions of each report was the only way I could see around this. The ability to specify expressions for more of the properties would be a really powerful addition to the Report Builder.

In conclusion…

So there are my tips for Report Builder survival: save as, do it often, and restart often too. Avoid doing anything too wacky, and keep your changes small and incremental. Keep off the hard liquor until you’re done with your project. Better still, try one of the other reporting solutions out there – I know I will be next time.