The importance of documentation in managing IBM Planning Analytics/Cognos TM1

Back to News & Blog

The importance of documentation in managing IBM Planning Analytics/Cognos TM1

The backbone of IBM Planning Analytics is the IBM Cognos TM1 engine, a proven, well-loved and solid platform for developing budgeting, planning and reporting solutions. Organisations invest in TM1 due to its powerful, flexible and functional abilities, enabling them to develop solutions that can evolve as their requirements change.

With such a scalable solution, it is important to ensure that controls and governance are put into place to manage your solution effectively, otherwise, the very strengths of the platform can quickly become risks.  Documentation can play a very important role in helping you to maximise your use of IBM Planning Analytics/Cognos TM1 and to reduce risk.

Let’s look at the strengths of TM1 and some of the potential risk areas which need to be managed.


TM1 has the ability to be as simple or complex as you require. However, even the simplest of solutions is likely to contain one or more data sources, numerous calculations to model business logic, processes to enter data and various reports. Common drivers of complexity include:

  • Business logic and modelling
  • Volume of TM1 objects and models
  • Interconnectivity of models
  • ETL (extract, transfer, load) routines
  • Custom interfaces and coding


TM1 allows models to be built rapidly, adapted and evolved throughout their life cycle. Changes can be made on the fly or in a more controlled environment. Because of the interconnected nature of TM1, making these changes often introduces risk. Upstream and downstream models and reports may be affected and what is more, this may not be immediately obvious. Whilst having good practices in place (such as separate development environments, change control and effective UAT) significant time is often taken:

  • Collecting information to perform an impact analysis
  • Identifying the areas that need to be tested
  • Recording and documenting changes


The flexibility of TM1 means each solution can be developed to meet the individual needs of the business. This is a significant strength and it is important to ensure that:

  • Standards are in place that address naming conventions and proven practices
  • A governance and quality assurance process is in place
  • A holistic view of the models is available so that you can check for consistency and monitor against the standards

Potential Risks to your organisation

What happens when things change in TM1?

Not only are changes made to the models and applications but over time people move on or simply forget. It becomes very difficult to keep track of the intricacies of solutions unless the model and its applications have been clearly documented and the documentation has been kept up to date. So, how do you reduce the risk which this brings with it? Well, in our experience we recommend you build a framework.

Building a framework to reduce risk

We believe that fundamental to reducing risk is maintaining detailed, concise and accurate documentation of your solution. We have found this is essential in enabling you to in maximise return on investment, saving you time, reducing risk and getting more from your solution. Below we have set-out an example framework for documenting TM1 that focuses on managing the characteristics of TM1 identified above. The framework is expressed in terms of what to document and the key characteristics that make the documentation effective.

What to document?

  • Data flows, relationships and dependences
  • Definitions
  • Changes to models
  • Rule Scripts & ETL process scripts
  • End user applications
  • Admin processes
  • Standards, proven practices and supporting information
  • Setup and configuration
  • Characteristics of Effective Documentation

Recommended characteristics/features to include in the documentation

  • Up-to-date – essential in an environment like Cognos TM1 which embraces change
  • Focused and relevant
  • Organised – effectively with good navigation and interactivity
  • Easy to maintain – there should be minimal time and cost involved
  • Graphical and visual – diagrams so that solutions can be seen holistically
  • Searchable – having documentation that can be searched intuitively
  • Centralised – the documentation should be centralised and easily accessible

How do you achieve the recommended level of documentation?

At HAYNE, we know from bitter experience that achieving the level of documentation required is extremely time-consuming if not impossible if it is attempted manually. We have searched for and experienced many software solutions which support TM1 documentation – what we found was QUBEdocs. QUBEdocs basically takes care of your TM1 documentation and models as we have explained in the above article. Along with our extensive understanding of the finance team, our breadth of experience of implementing, supporting and consulting on IBM Cognos solutions, we believe that the addition of QUBEdocs to your TM1 solution can make a seriously big impact to your business. It’s an investment into your existing TM1 solution which will reduce risk, free up precious time and allow you to flex and grow easier through effectively managed models and documentation.

What next?

Watch the video below, request a free demo or contact us to see how QUBEdocs, a simple ‘add-on’ software could transform the way you handle your IBM Planning Analytics/IBM Cognos TM1 solution.

Print Friendly, PDF & Email

Share this post

Back to News & Blog