IBM Cognos Report Studio is a tremendously flexible and useful application for querying and presenting data in a multitude of forms. From crosstabs to graphs, details or summaries, sales reporting to financial statutory reporting, Report Studio is both powerful and versatile.
Due to its expansive feature set and extensibility, every report developer will have their own approach to development. When inevitably under deadlines, even the most experienced developer is pressured to skip important steps that may seem unnecessary at the time.
Developing a consistent and disciplined methodology around the creation and modification of reports is a habit that can actually save time and effort. Consider the following suggestions when developing new reports or modifying others to make the most of your time and to avoid the frustration that comes with modifications and requirement changes.
#/* Comment */#
Liberally use the #/* comment */# syntax to internally document formulas, filters and other particulars of your report development. These can prove invaluable to recall changes when returning to a report after a period of stability. Commenting out a previously used formula, dating changes or even noting the business user requesting the change can be useful inclusions.
Version your work
Which copy of your work is current? Unless you have a robust version control system in place, this question causes headaches. Versioning your report copies with the date as shown below has a couple of distinct and concrete advantages.
Report Name vYYYYMMDD
Example: Financial Statement v20141122
- Firstly, there’s never a question of which version is current. The most recently dated version is the current one. This naming and date convention also sorts reports appropriately within Cognos Connection.
- Secondly, previous known good versions exist to which you can revert in the event of irreconcilable errors. I typically have an archive folder to which I immediately move old versions in case I need to revert.
- Finally, and perhaps most importantly, habitually creating a well-labeled new version when presented with new requirements establishes an implicit release process. The newest appropriately named copy becomes your current ‘Development’ version. When it’s ready to test it can be moved to the test package or other user accessible location for validation and verification. Once this ‘Test’ version is approved, the ‘Production’ version can simply be a view that is repointed to the final validated and approved copy of the current version. (This view is essentially where the user always goes to for their most up to date version. The name or location of this never has to change, providing a consistent user experience.)
Organize and label reports and objects.
While elaborated on by my colleague in a previous post, it’s worth mentioning again. If report objects are well labeled and kept orderly, they will be easier to locate and change. This is especially true as none of us are working on just a single report at a time! Returning to a well-organized report saves the mental switching costs of re-familiarization.
- Clearly label query items as they’re created. Make use of the query item ‘Label’ property by which to create report output labels.
- Use mock query items. Create placeholder query items (with expression value of 0 or some other neutral value) that are used solely for organizing the query data. Visual landmarks are created, making the job of quickly identifying groups of query items easier.
- Use mock filter items. The above technique can also be applied to filters. Well labeled filters allow quick navigation and will make the job of modifying your work, either by you or others, much more straightforward. How many times have you disabled a filter only to forget whether it was originally required or optional?!
Copy and paste the following within a query in Report Studio to get the mock filters shown in the image above.
[CLIP – Report Studio Filter Sections.txt]
- Organize reports. One axiom I adhere to relentlessly is to place all reports within the Framework Manager package upon which they’re based. I find it useful to have a ‘Development’, ‘Test’ and ‘Production’ version of each package for these respective purposes. If the users need the reports to be accessible from alternate locations, views are employed. This approach disconnects the ‘Presentation’ of the reports from the release cycle and needed organization. It undeniably adds time when moving a report through the release cycle; however the benefits of stable testing and insulating users from changes are invaluable. (This multiple phased package approach is also useful as Framework Manager will also automatically document the last published date for each, helping keep package versions under control as well. If you are subject to someone else’s organization of the packages, try employing your own report folders which correspond to report packages.)
Document report changes
One of the first things I do when creating a new report is to create a documentation page within the report to record feature requests and requirements changes. Report studio isn’t intended to be a word processor, but creating a blank page with a table full of empty Text Items can be used for documenting relevant project dates, feature requests and key stakeholders, as well as serving as a change log for report versions.
Copy and paste the following text into the Page Explorer in Report Studio to include a change log template.
Of course you don’t want your documentation page to render along with the report. Use a Boolean variable to control its display. I typically create a ‘Do Not Render’ variable with an expression of 0=1 which always renders false and will never render under any condition. I am able to view the content in the documentation page, while report consumers cannot.
While these tips are not entirely comprehensive, they hopefully represent some guideposts that can keep your development cycles clean and humming without the added noise of rework and expensive mental switching costs. And maybe – just maybe – they can keep you sane in light of ever changing business requirements!
