Read­ers of this blog or the CF-Talk mail­ing list over the past cou­ple of weeks may have noticed I’ve been hav­ing some angst about a project which used the Cold­Fu­sion Report Builder for some quite com­plex reports. One of my tasks was to cre­ate a final report which con­di­tion­ally pack­aged up some of the other reports as sub-reports, with the addi­tion of some cover pages, sum­maries and def­i­n­i­tions. There was also some refor­mat­ting and addi­tion of the company’s brand­ing to the nine exist­ing reports.

Over the course of this exer­cise some quite dis­turb­ing facts about the Report Builder came to light. Rather than just bash the prod­uct (which is quite tempt­ing) I’ll focus here on tips for help­ing you to work with it, should you ever have to.

Just a note: the prob­lems listed here were repro­duced on two of my own machines, and in some cases the machine of a col­league and a dev server as well, all with vastly dif­fer­ing setups – so these are, to my mind, fairly well-confirmed bugs, not one-offs caused by one par­tic­u­larly quirky con­fig­u­ra­tion. It’s also worth not­ing that this is using the lat­est ver­sion of the Report Builder avail­able to date, build 118586.

File Over­write Bug

First and most annoy­ing is the bug which occurs when more than one doc­u­ment has been open: save a report, and it will ran­domly rename the file to the name of one that has also been open in the same ses­sion. The unlucky over­writ­ten doc­u­ment doesn’t even need to be open at the same time. To illus­trate, imag­ine this: open “a.cfr”, then close. Open b.cfr. Make a change to “b.cfr” and hit save. The file­name mag­i­cally changes to “a.cfr” and that file is over­writ­ten. This occurred for me about half the time when work­ing with mul­ti­ple files. Clos­ing the report builder down between doc­u­ment edit­ing ses­sions did not help.

Work­ing around this bug was for­tu­nately sim­ple, although a bit annoy­ing: use Save As instead of Save. I took to incre­ment­ing a num­ber in the file­name – Report1.cfr became Report2.cfr became Report3.cfr, etc. Right now, my work­ing direc­tory has 146 ver­sions of the same file. At least there’s an incre­men­tal record of every change made. This had a sec­ondary ben­e­fit with work­ing around the next bug: the 100% CPU usage bug.

But first, one quirk of the Report Builder that may not be imme­di­ately obvi­ous – you can’t rename a .cfr file out­side of the Report Builder, and then pre­view it from within the Report Builder. This is because the path to the cur­rent file is stored as an editable prop­erty of the report – if you rename the file using Save As, the prop­erty is updated, but if the file­name is changed out­side of the pro­gram, you’ll need to update that prop­erty as well (it’s a prop­erty of the top level of the report).

100% CPU Usage

Tech­ni­cally, this bug is not a Report Builder bug, it’s a Cold­Fu­sion or JRUN bug. It works like this: make a small change to a report and pre­view (PDF for­mat). JRUN hits 100% CPU usage. I could find no rhyme or rea­son with this bug – and see above, this is with 146 sep­a­rate ver­sions of one file to test with. I’d make a sim­ple change – increas­ing a top mar­gin width and a left mar­gin width, for exam­ple. Pre­view, JRUN hits the ceil­ing and stays there. After end­ing processes and restart­ing ser­vices, I go back to my pre­vi­ous ver­sion of the file, and make one of the changes – just the top mar­gin, for exam­ple. Pre­view: suc­cess! Next, make sec­ond change (in this exam­ple, left mar­gin width). Pre­view: voila, suc­cess again. Final file is iden­ti­cal in every con­ceiv­able way to orig­i­nal file which caused JRUN to panic; it just went through two iter­a­tions to get there instead of one. Some­times it was chang­ing an item’s prop­erty that caused the CPU to spike, and the fix would be to remove the item, save and pre­view, then add it again with the new prop­erty value instead of the old.

What­ever the bug was caused by, the safest way to avoid it was to make a small change, note the file num­ber and what was changed, save and pre­view. If the CPU jumped up to 100% for more than about 20 sec­onds, kill the process, restart it, and go back to the last work­ing ver­sion of the file. Make the change in a dif­fer­ent way if pos­si­ble and repeat. It only took me 146 goes to get it right. In fact I stopped using the remote devel­op­ment server like I usu­ally do and installed Cold­Fu­sion locally on my machine, just because remote ser­vice restarts quickly got tedious.

Nested Sub-Reports Cause Report Builder to crash

My mother-of-all-reports con­sisted of a cover page, sum­mary, two pages of def­i­n­i­tions, four stan­dard sub-reports, one to four optional sub-reports, and a big fat legal dis­claimer at the end. Of the eight sub-reports, only one con­sisted of other sub-reports (six sub-sub-reports, in this case).

The Report Builder doc­u­men­ta­tion states some­where that nested sub-reports are sup­ported in the engine, but only one level will dis­play in the Report Builder itself. The real­ity is that nested sub-reports work fine, except if you’re try­ing to work with the top level report in the Report Builder. Any kind of scrolling around the doc­u­ment causes access vio­la­tions, and too much scrolling causes the access vio­la­tions to stack up until you can’t close the report builder because you can’t close the error mes­sages fast enough, which is a bunch of fun. The only way out then is to end the process through the task man­ager and start over.

To work around this bug I added the sub-report con­tain­ing other sub-reports and pre­viewed imme­di­ately (with­out mov­ing around the doc­u­ment) – and after con­firm­ing it was work­ing, removed the prob­lem report until the very last minute when the report was oth­er­wise com­plete. This meant the process was com­pleted with only three or four access vio­la­tions being thrown. I wouldn’t want to work with mul­ti­ple sub-reports – luck­ily there was only one in this instance.

The mys­te­ri­ous HTML For­mat­ted Text property

The lat­est build of the Report Builder included a new prop­erty for text objects – HTML For­mat­ted Text (true or false). It’s not in the pro­gram help or in the live­docs. Basic HTML that I tried – para­graphs, Hx ele­ments and strong ele­ments – didn’t seem to work – the markup showed in the ren­dered report. Through a process of trial and error, I dis­cov­ered that <b> ele­ments do work. Other presentation-style HTML such as the <i> ele­ment prob­a­bly also work.

Ran­dom Report Builder crashes

The instance of access vio­la­tion errors and sud­den spon­ta­neous pro­gram quits were quite high, and seemed to increase with the length of time that the pro­gram was open. Report Builder aver­aged around two to three inex­plic­a­ble crashes per hour of use for the three days I worked with it. Fre­quent restarts are a good idea.

Here’s another fun one: in order to get my sum­mary pages and sub-reports with page breaks in the right spots, I mis-used the group fea­ture with­out a group vari­able to cre­ate sec­tions. This worked quite nicely. To start with, I couldn’t remem­ber 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 descrip­tive. When group “5” was changed to its real name, “Analy­sis”, the Report Builder decided to change every prop­erty that had a 5 in it in the report to say “Analy­sis” too. The sub-report stopped show­ing up because Report Builder started look­ing for a file called ReportAnalysis.cfr instead of Report5.cfr. The default para­me­ter being passed into the report changed from “58” to “Analysis8”. Any­thing that should have been “5” changed to the string “Analy­sis” through­out the report. Why not hey? I can’t even begin to explain that one!

Another one: don’t try to be clever and spec­ify a neg­a­tive mar­gin value. As my sub-reports were designed to be stand­alone reports as well, they had their own mar­gins. These mar­gins were being added to the mar­gins of the par­ent report, caus­ing all sorts of for­mat­ting prob­lems. There doesn’t seem to be a way to spec­ify dif­fer­ent mar­gins for dif­fer­ent pages/groups/sections, and one of my exper­i­ments was to try to spec­ify a neg­a­tive mar­gin – how­ever this just resulted in an error dia­log that couldn’t be exited (the report builder process had to be ter­mi­nated from the Task Man­ager). As for the mar­gin issue itself, the cre­ation of two ver­sions of each report was the only way I could see around this. The abil­ity to spec­ify expres­sions for more of the prop­er­ties would be a really pow­er­ful addi­tion to the Report Builder.

In con­clu­sion…

So there are my tips for Report Builder sur­vival: save as, do it often, and restart often too. Avoid doing any­thing too wacky, and keep your changes small and incre­men­tal. Keep off the hard liquor until you’re done with your project. Bet­ter still, try one of the other report­ing solu­tions out there – I know I will be next time.