This document is intended to provide guidelines around developing business intelligence content and deploying it from one environment to another. For example, deploy content from a Development environment to a Quality Assurance (QA) environment, and then to a Production environment.
This document was written and tested against IBM Cognos 8.4.1 and IBM Cognos 10.1.
Exclusions and Exceptions
This document will not discuss IBM Cognos BI hardware and software configurations, or performance tuning. It also does not provide step-by-step instructions on configuring deployments. That information can be found in the core documentation.
This document assumes readers have experience with IBM Cognos BI, in particular IBM Cognos BI report administration and IBM Cognos Framework Manager.
Although people are familiar with the concept of development, quality assurance (QA), and production environments, often questions arise with respect to best practices for IBM Cognos BI. Some examples of these questions are:
- “How many physical environments do we need?”
- “Where is the best place to implement security?”
- “Where should we create report views, jobs and schedules?”
- “How many instances of our reporting database do we need to accommodate development, QA, and production?”
Depending on who you speak with, the answer may vary; in some cases to a small degree and in others to a large degree. While most people will agree to a three tiered approach to the BI life cycle, development, QA, and production, they may not agree on how many environments and databases are required or the hardware behind each.
This document will look at the pros and cons for different implementations of a three tiered approach (as described in the table below and as seen in Illustration 1) for the BI life cycle. It will also provide some guidelines around when and where to implement certain aspects of your BI project such as security, creating schedules, jobs, and so on.
|Create/Edit, Test, and Publish Framework Manager Packages||Validate Report Functionality, Data, and Security with a Limited User Base||Verify Content and Go Live|
|Organize Portal Folder Structure as Required||Test Performance for Reports, Jobs, and Schedules||Implement any Approved Production changes|
|Create & Test Reports/Report Views, and Apply Security||Deploy Content|
Illustration 1: Three tiered deployment flowchart showing Development, QA, and Production environment tasks
Illustration 1 shows how models and reports are developed, tested, and organized. Once the content is ready, it is moved into the QA environment for validation and testing, and then finally moved into the Production environment for consumers.
Physical Environments and IBM Cognos BI Instances
It is important to note that the three environments discussed in this document (Development, QA, and Production), do not necessarily mean three separate instances of IBM Cognos BI or even three physical environments. For example, Development and QA could be two IBM Cognos BI instances on one set of hardware. Development and QA could also be located in one IBM Cognos BI instance separated by folder structure, a folder containing development content and a folder containing QA content. Ideally, each environment would be located in three separate IBM Cognos BI instances each on their own hardware. This reduces risk and resource conflicts between development, testing, and production activities. To ensure performance testing is accurate, the QA environment would be a mirror image of the Production environment. If not, ensure the QA environment is configured for maximum benefit of the physical hardware being used. Should you put more instances on one set of hardware (this includes the use of virtualization), you may introduce a single point of failure for your environments. Fail over should be taken into consideration in any implementation.
Factors in Choosing a Deployment Methodology
The deployment methodology you choose will depend on several factors, such as cost, resources, policy, preference, and so on. Some may prefer a more streamlined approach with less servers and less work-flow process, while others with stricter policies based on risk management may require more checks and balances before moving to the Production environment.
Third Party Content Management Options for IBM Cognos BI
It should also be noted that third-party software exists to help streamline and simplify the deployment process. MotioCI from Motio, MetaManager from BSP software and NetVisn from Envisn are three examples of software based on the IBM Cognos BI SDK that enrich the maintenance and deployment process. This software allows for granular access to all objects in the IBM Cognos BI content store and easily allows you to backup and deploy content from one environment to the next. Should any of the guidelines provided in this document conflict with your strategy or requirements, consider looking at a third-party tool to enhance the deployment and metadata management experience.
This document will only provide guidelines for “out-of-the” box functionality and how it pertains to each of the tiers to be discussed throughout this document. This document will also focus on three physical instances of IBM Cognos BI for simplicity, one for Development, one for QA, and one for Production.
One environment that has not been discussed yet, but is certainly worth mentioning briefly here, is a test environment or sandbox. This would be a separate implementation of IBM Cognos BI all together as it would be used for “proof-of-concept” type work.
For example, testing configuration file changes, implementing portal customization, testing software upgrades, or testing content migration all have the potential to break the environment. Using a sandbox shields the Development, QA, and Production environments from this risk.
Having this environment as an image would be ideal so that you can easily revert back to a certain point in time should some of the testing render the environment unusable.
This section will look at the activities that should typically occur in the Development environment as highlighted in Illustration 2, which consists of the following tasks:
- Create/Edit, Test, and Publish Framework Manager Packages
- Organize Portal Folder Structure as Required
- Create & Test Reports/Report Views, and Apply Security
- Deploy Content
Illustration 2: Three tiered deployment flowchart highlighting the Development environment tasks
How Many Data Sources Do You Need?
Before taking a look at each of the individual Development environment tasks, let us take a look at data sources and how many instances of each you should have for your different IBM Cognos BI instances.
The Development environment should go against its own version of the reporting data sources since some report development can inadvertently create resource intensive queries that may affect performance of the data source. The QA environment could potentially share the same development data sources providing that when performance testing is done, development is halted so that more accurate performance results can be obtained.
To create a predictable testing environment, a static version of the data sources with smaller data sets can be used so that developers and QA testers alike know what values to expect and do not have to be concerned with constantly changing data. On the other hand, developers and QA testers may need to go against the same data as in the Production environment to troubleshoot certain report issues or data concerns reported by consumers as well as test report performance. To that end, both the Development and QA environments can create two connections for their data sources, one to the static database and one to a mirror of the production database. The Production environment simply points to the production database. This type of setup is seen in Illustration 3.
Illustration 3: Development and QA environments both pointing to static and production mirror databases, while the Production environment simply points to the production database
With this type of setup, any user who has permission to use both connections for the data source will be prompted which one they would like to use at run time. Users who only have access to one connection will not be prompted and will simply use the one connection they have access to.
Performance and load testing in the QA environment should go against the full production data set to ensure accurate results before deploying to the Production environment. Again, the closer the hardware specifications are in the QA environment compared to the Production environment, the more accurate the testing results will be.
Now let us take a look at each of the tasks presented in the flowchart in Illustration 2.
Create/Edit, Test & Publish Framework Manager Packages
In this initial and iterative stage of development, models are designed and tested, object and data security is applied as required in the model, and packages are created and published to IBM Cognos BI. This process is iterative since testing results or new requirements may require changes in the model.
With respect to publishing packages to IBM Cognos Connection, consideration should be given to the organization of the packages prior to publishing them. The packages should be published to an organized structure intended for final presentation to end users in the Production environment. In other words, ensure the final presentation folder structure where the packages will reside is in place. The reason for this is to ensure that Framework Manager's Analyze Publish Impact feature can be leveraged.
The Analyze Publish Impact feature is used to determine how modeling changes can affect existing reports. When using the feature, it looks for the package that was previously published and compares it with your model in Framework manager. If the package was moved in IBM Cognos Connection, then the Analyze Publish Impact feature will not work as it is unable to locate the published package for comparison. Since you can quickly configure IBM Cognos Framework Manager to point to different IBM Cognos BI gateways (in this case your QA or Production environments), you will want the same folder structure across environments to take advantage of the Analyze Publish Impact feature. For example, there may be instances where you want to analyze the publish impact on ad hoc reports in the Production environment which are not in the Development or QA environments.
Organize Portal Folder Structure as Required
The way in which you organize your portal folder structure will depend on several factors including work flow, taxonomy, presentation, and so on. There are no right or wrong answers, but some guidelines and considerations will be presented here.
Report Development Work Flow
Let us start with the report development work flow and report organization considerations. Typically a group of report authors will be identified to create “canned” reports for report consumers and typically their work flow consists of:
- developing and testing reports and maintaining versions
- moving finished reports to their final location
- updating reports based on feedback and then replacing them in their final location
Where authors develop their reports is a consideration that should be made. Authors can develop their reports in their My Folders and maintain versions of their development through report copies and naming conventions (Report 1 version1, Report 1 version 2, and so on) and then once finished, can place the final copy of the report in the associated package or folder used for final presentation to consumers. The down side to developing in My Folders is that others do not have access to the content except system administrators.
Another option is to have a Report Development folder under Public Folders that authors have access to and can organize as appropriate. For example, folders can be created to represent the package names the reports will be linked to and within those, folders with the author's names can be created as seen in Illustration 4.
Illustration 4: Development folder containing a package development folder which contains report authors' folders
This provides a more collaborative environment. Security can be applied as required to prevent people from inadvertently altering reports.
Once development of a report is completed, the report can be moved to its final presentation location where consumers will eventually access the report. That content is then deployed to the QA environment for testing. As testing is conducted in the QA environment, the report may require additional work at which point the author continues to work on the report in their report development location (My Folders, or a report Development location in Public Folders) and then eventually replaces the report in its final presentation location before deploying to the QA environment again.
Where Should Final Reports Go?
Regarding the taxonomy of the Public Folders' structure, a question that often arises is, “Where should we put our reports? Should they go in the package the reports are linked to or in a separate folder?” With out-of-the box functionality this will depend on how you intend to continually deploy your content.
By keeping your reports organized in the package they are linked to, it is very easy to keep track of your reports and instantly know which package they belong to without having to look at their individual properties. Deploying the package and its related reports is simple in this scenario. Report authors simply place their final reports in their related package and that package is deployed to the QA environment as seen in Illustration 5.
Illustration 5: Moving reports from development location to packages and then deploying packages to the QA environment
Once the packages and their reports are tested, they can be deployed to the Production environment.
The down side to this type of report organization can occur when dealing with large volumes of reports. For example, if you have hundreds of reports and make a change to the underlying package model that does not affect the reports, deploying the updated package from one environment to the next involves deploying all the reports it contains as well. While this may not show a noticeable impact on the deployment performance, you are still unnecessarily moving reports from one environment to another. This may also introduce the risk of deploying undetected changes to reports. A report may have been changed but no one was notified. That report may be deployed to the QA environment, not tested, and then subsequently deployed to the Production environment at which point undesired results may occur. One way to avoid this is to verify the last modified date of each report in the package and ensure the date is not greater than the last deployment date. If it is, that report must be tested in the target environment.
Another option is to create a folder separate from the package with a naming convention that indicates which package the reports are linked to. For example, reports based on a package called GO Sales could reside in a folder called GO Sales Reports. In this scenario, reports and packages can be deployed separately if desired as seen in Illustration 6.
Illustration 6: Moving reports from development location to reports folder based on a particular package which allows reports and packages to be deployed separately
Again, the core functionality of IBM Cognos BI only allows the deployment of packages and folders, not individual reports. The same issue can arise in this scenario where modified reports may inadvertently be deployed to the next environment. Again, one way to avoid this is to verify the last modified date of each report in the folder and ensure the date is not greater than the last deployment date.
This may be acceptable in some organizations, but some organizations may require that any deployed objects be retested. In those cases, a deployment folder can be created and any modified reports are placed in their final location as well as in a Deployment folder. The Deployment folder is then deployed to the target location and the reports are moved from the Deployment folder to their appropriate location as seen in Illustration 7.
Illustration 7: Moving reports from development location to reports folder based on a particular package as well as a Deployment folder which allows only modified reports and packages to be deployed separately. Once in the target environment reports are moved from the Deployment folder to their appropriate location.
The Deployment folder should be cleaned out once the reports are all moved to their target locations to prepare the Deployment folder for the next deployment.
Using the Deployment folder method can work in both directions. For example, if someone creates a report in the Production environment that can be enhanced by report developers and made available to consumers, it can be deployed back to the Development environment using the Deployment folder method.
The Deployment folder method requires clear communication between the report developers, the administrator conducting the deployment, and potentially a report administrator (if not the same person doing the deployment) to ensure the reports are deployed to the correct location in the target environment.
Again, for more control over granularity when moving objects from one environment to another, consider some of the third-party software options mentioned earlier. These can reduce checks and balances and make the deployment process easier and allow you to use a simpler taxonomy as shown in the first illustration for this topic, Illustration 5.
In some cases, folders containing several reports that are based on different packages may be required. For example, a folder for executives may contain several reports on various aspects of the business, each based on a different package. Again, in this scenario, to find out which package the report is linked to requires looking at the report properties. Rather than moving the reports to this type of folder, consider using shortcuts or Report Views. With shortcuts however, you need to take into consideration that when the source report is renamed or moved, the shortcut will break. Report Views on the other hand are more robust and provide extra flexibility which is discussed in the next section.
Create & Test Reports/Report Views, and Apply Security
Once a report development work flow (discussed earlier) has been decided on, authors simply create and test their reports until they feel they have met the report requirements. Once they have finished, they place their reports in the final presentation location and possibly a Deployment folder. Authors may also wish to create and test Report Views for reports where it makes sense.
When and Where Should Report Views be Created?
Report Views are a great option when trying to extend reports to meet different criteria based on filtering. For example, one report can serve several regions by creating a Report View for each region and supplying the appropriate region filter for each Report View. Authors would test these Report Views to ensure the filters are behaving as expected.
Report Views, as stated earlier, can also be useful when gathering a custom set of reports from various locations in the portal to serve a particular group of people. For example, a collection of report views can be used to present executive reports as seen in Illustration 8.
Illustration 8: Reports from Package 1 and Package 2 presented as report views in an Executive Reports folder
In this way, report consumers can go to a specific location in the portal to see reports of interest to them while the original reports remain organized according to your decided taxonomy.
Should the original reports be renamed or moved, the Report Views remain unaffected. However, if you do rename or move the underlying reports, you will need to deploy that content for the Report Views to work in the target environment.
Renaming or Moving Content and then Deploying
If you rename objects or move them, understand that when you deploy the modified content, you will simply be adding this modified content to the target environment. For example, you have a report called GO Sales Revenue in the GO Sales package in both your Development and QA environments. If you rename the report to GO Sales Revenue by Region in the Development environment and then deploy it to the QA environment, it will not replace the existing GO Sales Revenue report with the newly named report. It will simply add the GO Sales Revenue by Region report to the target location. This is the same type of behavior you would see on an OS file system. If the intent is to rename or move the item and have that reflected in the target environment, you can either delete the folders and packages in the target environment before deploying allowing for a clean import, or import the new content into the target environment and manually clean up items you no longer need.
When and Where Should Security be Applied?
This document will not go into the details of how to apply security but will provide some guidance around considerations that should be taken.
You can secure IBM Cognos BI content using groups and roles defined in the Cognos namespace or by using users and groups from an authentication provider namespace. Using groups and roles from the Cognos namespace allows your security to be portable from one environment to the next regardless of the authentication provider used. However, when you deploy from one environment to the next, you will need to duplicate efforts if the authentication providers are different. In those cases, you will need to add the users and groups from the authentication namespace to the groups and roles in the Cognos namespace since they will not be the same from one environment to the next.
If you are using the same authentication source instance for each of your environments, you can implement security in the Development or QA environments, although, implementing security in the Development environment can help prevent inadvertently overwriting security that was applied solely in the QA environment. It is better to have one source of the truth which is carried forward from the Development environment to the QA and Production environments to reduce the risk of losing work done in one environment with work done in another. In either case, you will likely implement security before deploying to the Production environment to reduce the risk of exposing confidential data.
If your environment uses separate instances of an authentication provider from the same vendor, for example, one instance for Development and QA, and one for Production, you must ensure they are mirror images of each other and that IBM Cognos Configuration is configured the same for the namespace in each environment. This will ensure there are no security conflicts when deploying from one environment to another.
Create a Deployment for Quality Assurance Environment
Once reports, report views, and security has been vetted in the Development environment, the content can be deployed to the QA environment.
What is included in the deployment will depend on where you are in the development and testing process. For example, the first time you deploy content from Development to QA or from QA to Production, you may wish to include data sources, signons, and access permissions, or even deploy the entire Content Store so you do not need to replicate work in the target environments (note: If there are multiple projects that will be deployed at different times, deploying the entire content store will typically only be an option for the first set of content to be deployed). On subsequent deployments, you may choose to include less or change the deployment configuration to prevent overwriting work done in the target environment.
If you are deploying on a regular basis, you can automate your deployments. The default output location for a deployment archive is <IBM Cognos BI install location>/Deployment. You can change this location in IBM Cognos Configuration to a common network drive accessible by the source and target IBM Cognos BI environments. The setting is found under Environment > Deployment files location. The IBM Cognos BI service must be run as a user that has access to the network location. Once this is configured, a deployment export can be generated regularly by the source environment based on a schedule and picked up by the target environment by a scheduled deployment import.
Quality Assurance Environment
This section will look at the activities that should typically occur in the Quality Assurance (QA) environment as highlighted in Illustration 9, which consists of the following tasks:
- Validate Report Functionality, Data, and Security with Limited User Base
- Test Performance for Reports, Jobs, and Schedules
- Deploy Content
Illustration 9: Three tiered deployment flow chart highlighting the QA environment tasks
Import Deployment from Development Environment
Now that you have the deployment package from the Development environment, it can be imported into the QA environment.
If it is the first time that the content from the Development environment is imported into the QA environment, then you will likely want to deploy the entire content store. For subsequent deployments of content, depending on the task, you might want to deploy just certain packages, folders, reports, and so on.
Validate Report Functionality, Data, and Security with a Limited User Base
Once the content is imported into the QA environment, it is time to get a limited user base, who are not administrators in IBM Cognos BI, to test the reports. These users should be familiar with the data for the most accurate results.
As mentioned in the Development Environment section, the QA environment can have two data source connections for the packages; one to a smaller, consistent data set, and one to a mirror image of the production database. This allows the test users to go against a limited data set for consistency testing, or a full data set to validate the latest numbers that report consumers will see, and test for performance.
The limited user base will also test security. They will see if they have proper access to the Studios, have the right capabilities, and check reports to see if model object and row level data security is working as expected.
Test Performance for Reports, Jobs, and Schedule
Report performance is one of the most important tests to perform. With an environment that mimics the Production environment, the reports can be measured on total execution time. As well, report administrators can see how reports, under full load, will run and see if they fall within acceptable business parameters.
If performance is not acceptable, then developers should be notified and should follow standard troubleshooting practices, such as checking report SQL and report design for efficiency.
Knowing how a report will perform will help in scheduling. Scheduling a report can happen at any time depending on business need, but there are a few things to consider. You should consider scheduling resource intensive reports during off peak hours to reduce the load on servers. Schedule reports appropriately. For example, monthly reports should be run on a monthly basis and not more than that, or some entries might only run based on an event or trigger such as a database refresh.
Creating jobs will help in lowering the administration in scheduling. A job is a collection of reports, views and/or other jobs with a single schedule.
Final Check Before Deploying to Production
After all the testing and validation, it is a good time for a final check on the overall report structure, report/report view names, and so on, before the deployment for the Production environment is created as this deployment represents what consumers will see in the Production environment.
If there are changes that need to be made to reports, security, structure, and so on, they should be sent back to the Development environment and then rolled forward, again, to maintain consistency between the environments.
Create a Deployment for Production
Once all the report functionality, security, report performance, jobs, and schedules have been tested in the QA environment, then the content can be deployed to the Production environment.
For a first time deployment, a deployment of the entire content store can be created that contains everything an end user needs in order to view/run their reports. Subsequent deployments can be broken down into smaller pieces such as by folder, package, division, etc, depending on the business need. Again, if you have multiple projects that will be deployed at different times, a full content store deployment would typically only occur for the first set of content or projects that are ready to go in the initial deployment into the next environment.
As discussed in the Development Environment section, how you deploy your content and what you deploy will depend on preference, tools, and requirements. Just like the Development environment, you can still automate deployments and place the deployment archives on a network location that your Production environment has access to. For granular deployments of reports and other objects found within packages and folders, you may choose to use the deployment folder method described earlier in this document, or use third party tools.
This section will look at the activities that should typically occur in the Production environment as highlighted in Illustration 10, which consists of the following tasks:
- Verifying Content and Go Live
- Implement any Approved Production Changes
Illustration 10: Three tiered deployment flowchart highlighting the Production environment tasks
The Production environment should be used to view report output or to create and run ad hoc reports only. Any development of existing “canned” reports should be done in the Development environment and migrated through the existing infrastructure following the steps recommended in this document.
Import Deployment from QA Environment
The initial deployment into the Production environment can be a full content store deployment from the QA environment. This will minimize efforts and create the foundation on which subsequent deployments can build upon. The QA and Production environments should match to ensure a smooth deployment. This includes authentication providers and data sources.
Upon subsequent deployments, once the content in the QA environment is ready to move to the Production environment, there are a few “out-of-the-box” options that can be used to deploy the content as mentioned earlier in this document. As a quick review, the options are to deploy:
- packages which also contain their related reports
- packages and corresponding folders containing package specific reports
- a deployment folder containing only objects to be deployed which are then moved to the appropriate location in the target environment
Once again, the use of third party tools such as MetaManager or NetVisn can aid in deploying single content objects such as report specifications, schedules, or packages from one environment to another as well as other enhanced maintenance capabilities.
Verify Deployment and Go Live
Upon the initial load of the Production environment, full testing should occur to verify that the reports all run, and that report output and timing fall in line with expectations. Once the production environment is opened to end users, subsequent imports can be tested as necessary depending on the existing policies of the organization.
It might seem redundant to verify the deployments if indeed the QA and Production environments are identical or match very closely. In fact there should be very little verification required especially if the environments are identical. However, given that the QA environment uses a mirror image of the production database, some testing and verification needs to be performed especially upon the initial load of the Production environment. It is possible that issues may exist if the two environments are separate installs. Configuration files, security, and database clients are just some of the areas which could affect the reports and packages in the Production environment.
It should always be a requirement, regardless of how close the environments mimic each other, that sufficient testing of the deployment and all related files from the QA to the Production environment be performed. The strategy for the verification of the deployment should be documented, and stringently followed each and every time a deployment is imported.
Implement any Required Production Changes
Situations may arise that an issue occurs in the Production environment which requires an immediate change to a report, security, or the environment configuration. Normally all changes should be migrated through the environments following the process defined in this document, which entails making the change in the Development environment, migrating it to the QA environment for thorough testing, and then finally into the Production environment. It is possible that a production impacting issue may exist that can not wait for the full deployment process to occur.
For example an issue with the security applied to a report may allow users to see more data than was intended. The report is critical to the management team and therefore cannot be taken off-line to go through the full deployment cycle to implement the required changes. In situations such as this, the fix may be implemented in the Production environment and then immediately rolled back to the Development and QA environments to ensure they are part of any new deployments moving forward.
Backward Deployment of Production Content
While the production environment is not intended for professional report development, the ability of users to create ad hoc reports generates the potential need for backward deployment of content from the Production environment to the Development environment. From time to time an ad hoc report may be created which may be considered valuable to other users and should be incorporated into the regular development cycle. In such cases, a Deployment folder can be used in the Production environment to deploy the ad hoc reports back to the Development environment. The reports can then be worked on in the approved development location and eventually placed in their final location for presentation to the end users. There may also be cases where the reports are kept as is since they are a good starting point ad hoc or analyses report.
Illustration 11 shows the flow of ad hoc reports taken from either a user's My Folder or from the Public Folder and moved to the Deployment folder. The Deployment folder is then deployed to the Development environment and the reports are moved to the development location. Once development is complete, the reports are placed in their final presentation location at which point they are ready to be deployed to the QA environment using the deployment method of choice.
Illustration 11: Moving reports from the Production environment location to the Deployment folder, then deployed to the Development environment, enhanced by report authors in the development location, and then moved to the final presentation location
There may also be cases where the Development or QA environments fall out of sync with the production environment due to change management process not being followed correctly. If the Production environment's content is accurate but the other environments are not, you may wish to deploy the Production environment's content, such as the packages and reports, backward into the other environments to replace their content.
In general, it is recommended that users take official training delivered by IBM Cognos trainers to ensure they are leveraging the IBM Cognos BI tools appropriately and to their fullest. However, it may not always be feasible especially for a large user base. For example, your organization may have hundreds or even thousands of users. Their training may simply involve how to use “canned” reports developed for them. This type of training is very specific to their business and data. In these cases, in-house training may be required. If this is the case, the QA environment is typically the best place to conduct this type of training as it does not conflict with report development or introduce risk in the Production environment.
Training and QA testing should be scheduled so that the two activities do not conflict.