Cognos Analytics Version Control

Rory Cornelius, November 1, 2017

Have you ever made a change to a report that broke something unintended? Maybe it wasn’t even the latest change but one you made an hour ago, or days ago, before someone noticed the issue. How do you quickly revert back to the previous version? How do you see all of the recent changes to figure out which one caused the issue? This is where version control becomes incredibly useful.

Table of Contents

What is Version Control?

Version control is a way to keep various copies, or versions, of source code, deployments, or in this case, report objects in an organized manner allowing you to compare and quickly revert to a previous one as needed. Ideally, it will also allow you to keep track of who made the change with the reasons for the change. One way to think about it is like a bookmark in time allowing you to go back to a point before the feature was added that broke the report.

Simple Version Control

The simplest form of version control is a completely manual process handled by the developer. As changes are made to the report definition, the developer does a Save As and renames the report to something like “My Report v1” or “My Report v2”. I might suggest making the standard something more like “My Report 20170914v2 – Added new singleton for date prompt” including a date, a version, and a comment to be able to track a bit more about what was changed and when. Depending on your request system, it could even include a request number of some sort to track why the change was made.

One way of keeping this organized might be to create a folder for report development that all developers have access to. Within that folder create a structure just like your reporting environment. For every folder in the main reporting environment, create a folder in Development. Then for each report being worked on, create a folder in the appropriate location with the same name as the report. There you can keep the versions of the report as changes are made. This allows you to easily find and keep track of all the changes for a particular report. You can also look at the report properties to see who changed it last if you have questions. If a new change is needed, create a new copy of the report with the next version number, that day’s date, and a comment saying “In Progress” so if any other developer looks in that folder, they can easily tell that it is being worked on. Once it’s ready to be deployed to production, remove the “In Progress” part of the comment.

Here’s an example folder and naming structure with report versions:

• Development Folder
  • Sales Department Reports
    • Sales YOY Variance
      • Sales YOY Variance 20170615_v1 – Initial Release
      • Sales YOY Variance 20170617_v2 – Added prompt info to the header
      • Sales YOY Variance 20170910_v3 – Added column for margin
      • Sales YOY Variance 20170914_v4 – In Progress – Adding additional optional prompts

This system works fine in some situations but it does have drawbacks, especially if you have a large and complex reporting environment.

First, it’s reliant on the developers to follow the standards that are in place. They have to make sure they are creating a new copy and putting in the date, version, and an appropriate comment. They also have to be sure to remove the “In Progress” portion or you end up with a whole folder of “In Progress” reports. Finally, as the number of reports you have grows over time, you end up with a lot of copies of the same report and no automated way to clean up old versions.

Deployment Based Version Control

Another option that could be used in addition to the above (or instead of it if you’re less concerned about having easily available back versions) is deployment based version control. Instead of keeping back copies of reports as they are developed, keep a copy of each report deployment. This works especially well for companies that have multiple environments for Development, QA, and Production. Once a report or set of reports is completed, create an export using the Cognos Content Management tool to be able to migrate the report to the next environment. Set up a labeling system to indicate which report changes are in each zip file and archive the zip files in a safe place. Then, if you need to revert to a previous version, you can easily track down the previous version of a report and create an import job to revert it back. This allows the version control to be managed within an existing deployment process and the copies to be held in zip files within a file system instead of within Cognos itself. It’s not as easy for developers to look back and requires some outside change tracking, but it does safeguard you if an issue shows up in Production that needs to be reverted to a previous version.

Motio CI

If you don’t want to deal with the hassle of those options, the folks at Motio have developed a product called Motio CI provides all of that functionality (and more) within an easy to use application that integrates seamlessly into Cognos. It behaves a lot more like other software development systems where there’s a centralized repository that allows you to check out, lock, and commit changes to reports. You can also apply changes to a particular deployment label making it very easy to migrate reports from one system to the next as well as revert back to a previous version of a report.

 Once Motio CI is installed, the Report authoring studio will have these extra icons added. The first is used to “check out” the report. This locks it so that no other developers can make changes at the same time preventing the situation where your changes get overlaid by someone else’s. The second icon takes you to the revision history for the report where you can see all the changes over time with comments and other information. You can also use the revision history screen to revert back to a previous version.

Once you check-out the report, the set of icons changes to these. You still have the revision history icon, but you now have Check-In and Undo Check-Out icons as well.

At this point, you can go ahead and make the required changes. Use the regular Save button as you normally would to make sure everything is saved back to the server. You can even close out and open the report again later. You’ll still have it checked out with your latest changes included. Once you’re finished with the change and ready for it to be promoted, you use the Check-In button which brings up this dialog:

Here you can type in a descriptive comment indicating what was changed and optionally also include a ticket number to be able to track it back to a specific request or issue. At the bottom of the dialog you can add the revision to a deployment label which allows you to group a set of changes together and deploy them at the same time. This comes in handy especially when there is a Framework Manager package change that causes several reports to need to be changed as well. All of these can be deployed together preventing any errors that might arise if one were to go in before the other. If there is an issue, all of these changes can be rolled back at the same time ensuring the rollback doesn’t cause any new problems.

If a problem does arise in a particular report, you can pull up the revision history and see something like this:

It lists all of the changes that have been checked in with date, author, and comments associated. The icons on the right give you options to revert, see more details, or even open that particular revision in Report Authoring. Having the ability to not only quickly go back to a working version, but to be able to compare what has changed, can save report authors a lot of time and effort.

MotioCI comes with a ton of other features too, including some very robust regression testing and the ability to track environment changes, among others, but version control remains one of the core pieces that can greatly improve report developers’ efficiency and ability to quickly react to problems. In the end, it helps everyone have a stable and trustworthy reporting environment with less downtime.

Conclusion

No one would think of developing a software product without using version control. Why would report development be any different? It’s a great way to protect yourself in the event a critical bug sneaks into your production system that needs to be reverted. There are several ways to approach it from manually making copies of reports to using a separate product like MotioCI, but I urge you to consider how your organization is handling version control now. Are you protected or could it use an overhaul?  Be sure to subscribe to our newsletter for data and analytics news, updates, and insights delivered directly to your inbox.

Next Steps

If you have any questions or would like PMsquare to provide guidance and support for your analytics solution, contact us today.