By Elwood Philbrick, Envisn, Inc.
Documentation for Cognos Analytics is one of those things that doesn’t come with it. You have to create it yourself or look for a third-party product that might meet all or part of your needs for documentation. Creating it yourself can be difficult primarily because getting access to all of the Cognos metadata required to make it successful is not easy.
So what would good documentation look like in Cognos Analytics? A well thought out approach to documentation would likely include the following:
- Complete – Covers all of the key attributes of every report object and models. This needs to be the answer to any question you would ever have about an object in your Cognos Content Store. Data sources, Models/Packages used, data lineage, filters, security, change history, security, owner, create date, specification, etc. – Everything!
- Easily accessible – Instantly available when needed. Go right to the documentation of any object whenever you need to. No archives to search through and its organized to mirror the layout of your Content Store.
- Automatic – No human intervention to create or maintain. A process that instantly provides it so your documentation is always up to date in real time.
- Intuitive – Organized for instant use. All object documentation follows a standard format so you can instantly find whatever you’re looking for.
- Forever – Covers an object’s usage life cycle and beyond. Would cover the current (active) version of an object along with previous versions of the same object all laid out the same way.
Let’s take a look at what these areas might look like starting with completeness.
Complete
In the figures shown below we see documentation for a report titled Order Summary. In actual practice this is a single, streaming web page that contains sections covering description, create date, active status and other key attributes such as package and model dependencies, data lineage, data sources, model usage, change history, etc.
For the sake of example these are being shown as single images to highlight key areas of the documentation.
Automatic
The documentation examples you’re seeing in these graphics are created instantly at the same time that the actual object itself is created. This is done through a process in conjunction with the Cognos Content Store. Whenever an object is updated or changed that new version is automatically documented and the previous version’s documentation is archived as part of a version control process, but is also available as reference within the documentation for the current version of the object.
Accessibility
Getting to the documentation should be as easy as getting to the report itself. For this reason the best thing to do is to simply organize all of the documentation in a way that follows how Cognos Analytics itself has structured its content. In the graphic below you can see how the documentation structure mimics that of Cognos analytics making it instantly available. Each item shown is a hyperlink for the same CA folder which contains each object’s documentation.
Note in the images below that the folder structure of the documentation is exactly the same as that of Cognos Analytics.
Intuitive
The flow and structure of the documentation goes from general information to a more detailed level such as data lineage, main query data items, database items, etc. All of the documentation for every object is organized the same way so you always know where to look. Plus, hyperlinks make it easy to quickly go to exactly what you need.
Forever
When a new version of an object is created it automatically becomes the active version for that object while all previous versions are also retained and archived. This makes it possible to compare any two versions from the past or the current version with any previous version (version control). Plus, for control reasons should it be needed, it shows exactly what the report contained for data, calculations, filters, etc. during a given time period.
This capability also makes it possible to capture all changes made from version to version over time (change history). See image 10 below.
An important point here is that because all of this metadata is available for each object in the Content Store, it’s available for analyses. This makes it possible to do analyses across the entire Cognos environment. So if you needed to know which databases or data items are used, and where they are used, this is a simple analysis to perform.
Summary
Does everyone that uses Cognos Analytics need this level of documentation to successfully manage their Cognos operations? Maybe not, but when you do need it can often be of critical importance particularly for things like HIPPA or SOX compliance. And knowing exactly what data are being used and where, along with how security is being applied, are also critical requirements in virtually every reporting environment.
Note: The examples used in this blog came from Envisn’s NetVisn product. Real time, detailed documentation is one of its many features and its breadth goes well beyond the examples shown here.
© 2020 Envisn, Inc. All rights reserved. Tools for Cognos
