cognos guidelines and best practices

COGNOS Coding Guidelines &

Best Practices

Author WIPRO ltd.

Creation Date 12 November 2008

Last Update Date

Version 1.0

This document is the property of Wipro Ltd. who own the copyright thereof. The information in this document is given in confidence and without the written consent of Wipro Ltd. given by contract or otherwise, this document must not be copied, reprinted or reproduced in any material form, either wholly or in part. Also the contents of this document or any methods or techniques available there from, must not be disclosed to any third party whatsoever.

ã 2008Wipro Ltd.

DOCUMENT CONTROL

Change Record

3

Date Author Version Change Reference

12-Nov-2008 Puneet Gupta 1.0.0 Initial Document

Reviewers

Name Position

Distribution

Copy No. Name Location

1 Library Master Project Library

2 Project Manager

3

4

Note to Holders:

If you receive an electronic copy of this document and print it out, please write your name on the equivalent of the cover page, for document control purposes.

If you receive a hard copy of this document, please write your name on the front cover, for document control purposes.

© Wipro Ltd 2 of 21

Table of Contents

1. Cognos Best Practices 4

2. Cognos Modeling Best Practices 6

3. Cognos Performance Tuning Tips 14

4. Recommendations on Cognos Reporting Architecture 14


1. Cognos Best Practices

IntroductionThis document is intended to provide a high-level collection of best practice guidelines on the use of Cognos 8 BI components. Whereas the Cognos manuals & help files explain what each feature of the product does, this document is intended to explain how best to use those features to get maximum results from your Cognos development.

Scope of the documentThis document helps all users, developers to understand each component of Cognos 8 BI and use right parameters for getting the efficient models, reports.

ModelsA model is a view of data. Cognos models present a view that makes sense for a particular end-user application, and specify how that view maps to the underlying data sources. For example, HR usually wants a personnel-oriented view of the company’s business.

Query ItemsA query item is the smallest piece of the model that you can put in a report. It represents a single characteristic of something, such as the hire date, designation for all employees. Relational databases call these as “columns”.

Query SubjectsA query subject is a set of query items that have an inherent relationship, usually 1-to-1. Relational databases call these “tables”. Each cell of a column is directly associated with the cell in the same position of all of the other “columns”. Relational databases call these associated cells “rows”.

Although the table concept is simple, query subjects are more complicated than that, because they specify a mapping between this tabular view and the underlying data. This is closer to the “view” concept of relational databases. In addition, the relationships between query items within a single query subject are not always simply 1-to-1. We’ll see this a bit further on with hierarchies.

RelationshipsWhile query items within the same query subject have an inherent relationship, query items in different query subjects don’t - we need something explicit to relate them. This is what model relationship objects do. For example, if I have employees and branches, I probably need to know what branch each employee belongs to. If this information is recorded in the Employees and Branches query subjects as a Branch ID, then the model needs an explicit relationship to say that the Branch ID in each query subject means the same thing as the Branch ID in the Branches query subject. This usually takes the form of an expression, such as:

[Branch].[BranchID] = [Employee].[BranchID]

Relational databases have a similar concept called a “join”.

Star Schemas


In the star schema view of data, set of facts are collected into one or more fact tables, and related to a number of independent dimensions. For example, a fact table might consist of orders for products. Each order has a number of aspects: the customer, the sales person, the product, quantity, and date of sale. While the quantity is self-describing, the others are not – each has their own set of characteristics, represented by a dimension. Reports may view the facts by any combination of dimensions: e.g., show the total quantity of items per year, across all sales person and products.

In multi-dimensional data stores, the relationships between the fact table and the dimensions are inherent. In relational data stores, the relationships are explicit. Cognos 8 uses the relational model regardless of the type of store: each dimension is a query subject, connected to the fact table query subject by a relationship object.

Hierarchy and Dimensional InformationIn most cases, a flat tabular or cross-tab of raw data cell values is not very useful to users. There is always some sort of hierarchy in the data. In a star schema, each of the dimensions is at a higher level of abstraction, or hierarchy, than the facts represented by the fact table: users almost always want to view the facts grouped by characteristics of one or more dimensions.

Within a dimension there is often additional hierarchy, such as year/month/day, or country/state/city. There are many days per month, so day is lower in the hierarchy than month. In a multi-dimensional data store, this hierarchy is inherent, as the relationships are. In a relational store, if each level in the hierarchy is a separate table, then the relationship cardinalities tells us what the hierarchy is. But if they are combined in a single table or query subject (i.e., “de-normalized”), we need to make them explicit. The Cognos 8 model does this with the Dimensional Information on each query subject.

Aggregation and UsageIn Cognos 8 BI, you tell the system what you want to see, and it figures out how to best to do that. If you ask to see years and sales amounts, Cognos 8 assumes that you want to see the total amount sold per year, rather than the amount for each of the thousands of sales that may have happened in each year. This is called “aggregation”.

Hierarchy is important for aggregation, because it controls how rollups are done. If I ask to see years, months, and sales amounts, the sales first have to be rolled up (aggregated) to the month level, then to the year level.

Cognos 8 needs to know what can reasonably be aggregated, and exactly how. For example, if I ask to see invoice ID numbers by year, it makes little sense to attempt to summarize this. If I ask for inventory quantities for a product by year, I probably want to see an average. Cognos 8 uses the query item usage property to determine what can be aggregated, and the Regular Aggregate property to determine how.


2. Cognos Modeling Best Practices

Query Problems

Framework Manager User Guide tells you how to get started building your model, and gives guidance to help you through the process. We’re going to assume that you’ve read that, and already know basically how to model using FM. What we’re going to do here is to show you a bit about what’s behind that guidance, and what can go wrong it you don’t follow it.

Selecting Join Paths

Whenever Report Studio uses query items from query subjects, it has to figure out how to relate them. This is done by tracing a path from one query subject to the other, using the relationships in the model. This is not always easy.

Multiple Paths (Role-playing Relationships)

Consider the following simple case, where each order has two relationships to customers: one for “Bill to”, and another for “Ship to”. In this case the CUSTOMER table plays two rules, each indicated by one of the two relationships.

But now we have a problem. If I ask to see order amounts for each country, how does Report Studio know whether I’m interesting in billing or shipping information? The answer is “if doesn’t”. So it picks one arbitrarily. If that’s not what you wanted, you may not even realize that you have the wrong answer, let alone why!

The FMUG tells you to solve it using shortcuts, like this:

(Note that the split is done at the “one” end of the relationship.)

Why does that work? Because now the Report Studio user/author implicitly tells the subsystem whether the point of interest is billing or shipping (or both!), simply by selecting query items


from the corresponding query subject. The system uses that information to automatically select the right relationship. Now the user has the right answer, and no-one is confused.

Why use shortcuts? - Because it makes the model easier to maintain. If I make changes to the way customers are modelled, I have to do it only once, in the CUSTOMER query subject, instead of once in “Bill to CUSTOMER” and again in “Ship to CUSTOMER”.

Follow the Arrows

OK, that was a simple one. But sometimes things can be a lot more complicated than that. In general, how can we figure out which query subjects to split into shortcuts, and which to leave alone, so that the result is unambiguous, but without taking away any query abilities?

Notice that the “many” end in crow’s foot notation looks a bit like an arrow pointing away from the query subject it’s attached to, toward another query subject that it depends on. In the case above, orders depend on customers but not vice versa. The notion that relationships have a direction is one that we’ll use quite a lot - this “arrow” points to the next higher query subject in the rollup hierarchy (more about this later).

These arrows give us a very useful technique for deciding how to fix model multiple join paths between query subjects. We’ll look at a few cases based on a generic “diamond” shape, and extrapolate from there.

For each case, we change the model so that the user will implicitly select the desired join perspective, just by choosing items from the desired folder. (Remember that a query subject looks like a folder to a report author.) We do this by duplicating one or more nodes, and distributing the relationships among them, just as we did above.


Common Rollup

The logical place to split this is at C:

Why? Because if each B has many A’s, and each D has many A’s, it’s quite likely I’ll want to view A’s from the perspective of both their B’s and their D’s (e.g., orders by customers or by date). But since each B has only one C and each D has only one C, it’s less likely that I’ll want to view both B’s and D’s as they relate to C (but more about this later).

Another way of looking at this is as a star schema: A is the fact table, with 2 dimensions B and D, each of which has a hierarchical rollup to level C.

Note: This is a very uncommon pattern. Possible real-life example: Fiscal Quarter (B) and Calendar Quarter (D) both roll up to Year (C). C1 is Calendar Year, C2 Is Fiscal Year. These should really be separated in the DB schema, as they usually have different attributes.

Now notice what we did: we started at A and followed the arrows along both paths until they converged at C – that’s where we split the diagram. But how do we know to start at A? Again, follow the arrows: start at any node, and follow the arrows backward until you can’t any more. That’s the “root” – in this case, A.

Let’s try this for some slightly different diamonds.

Ragged Hierarchy


Using the same rules as above, we get:

Note: This pattern is also uncommon. An example: Country, State, County, City, where some countries do not have states or counties. Common practice is to make the database hierarchy uniform, by inserting dummy data in the unused levels (e.g. by using the City value for State and County).

Multiple Fact Tables

This one is a bit more interesting, following the arrows backwards, we find two fact tables: A and C. This means that we have two stars, with B and D as common (conformed) dimensions:

This is a bit awkward: even though the conformed dimensions are really the same thing, we have to give them different names to allow them to be distinguished by usage. The FMUG tell you how to fix this, using namespaces:


Because a very common pattern, FM provides a wizard called “Create Star Schema Grouping” that makes it easy.

By the way - notice that in all of the other diamonds, the corrected model can still relate any two query subjects. In this one, we can’t relate A to C. Querying across fact tables is not easy. We’ll talk more about it later on. (See “Joining Fact Tables”)

Loops

We’ve dealt with 3 of the 4 possibilities with a 4-point diamond. The last one is the loop:

In this case, following the arrows leads us back to where we started. Every query subject in the loop depends on every other, directly or indirectly, including itself. In this case, the arrows don’t tell us where to break the diagram, so we have to use our knowledge of the data. Which table has the most rows? That one must be the fact table.

Let’s look at a simpler loop. An organization might be described by employee-branch-manager relationships, like this:

Which is higher up in the implied rollup hierarchy? It depends on the question you want to ask. If you want to know what branch employees belong to, then SALESBRANCH is above SALESSTAFF. If you want to know who the branch manager is, then the reverse is true.

We could provide answers to both of these questions by using the same technique as before (splitting SALESBRANCH this time). But there’s another question that this approach won’t allow us to answer: the name of each employee and that employee’s manager. I can’t just drag FIRSTNAME and LASTNAME twice onto the same report – that will just report each employee’s name twice on each line.


Using the rules above, and the fact that there are more employees than branches, we split the loop at SALESSTAFF:

Now I can pick LASTNAME from Branch Manager and from SALESSTAFF, and I get the employees that report to each manager:

Manager Employee

Béchard Béchard

Béchard Martin

Béchard Turpin

Béchard Samson

Bergström Nilsson

… …

Here’s what the generated SQL looks like. It has the joins I need to relate managers to staff.

Select distinct Branch_Manager.LASTNAME as Manager, SALESSTAFF.LASTNAME as Employee from "2 - GOSales1 - OLE-DB".GOSALES1.dbo.SALESSTAFF Branch_Manager, "2 - GOSales1 - OLE-DB".GOSALES1.dbo.SALESSTAFF SALESSTAFF, "2 - GOSales1 - OLE-DB".GOSALES1.dbo.SALESBRANCH SALESBRANCH where (Branch_Manager.SALESSTAFFCODE = SALESBRANCH.MANAGERCODE) and (SALESBRANCH.SALESBRANCHCODE = SALESSTAFF.SALESBRANCHCODE)

Note: the “distinct” keyword is generated by Report Studio’s automatic summarization feature, and reflects the fact that different managers may have the same last name. To avoid this, automatic summarization can be turned off in the report.

Recursive LoopsThis limited solution above assumes that loop is not really recursive (e.g., branches with sub-branches, managed by one of the parent branch staff). Reporting effectively in such models usually requires custom SQL. Most data warehouses convert these into fixed hierarchies. We won’t talk about this here.


Determining Hierarchy and AggregationThe FMUG contains an entire section on Dimensional Models, and explains how to avoid double counting in dimension rollup. We’re not going to rehash all of that here; we’re just going look at some key things from a slightly different viewpoint.

Using Relationships between Levels

In determining how to do rollups, Report Studio needs to understand what the rollup hierarchy is, and how it relates to the tables involved. Between query subjects, the relationships and their cardinalities determine the rollup hierarchy. For example:

Here the rollup is from City to State to Country. Country is at the top of the rollup hierarchy. To help report authors understand this, these query subjects should appear in the containing folder that represents that dimension, in top to bottom order in the hierarchy. Since the arrow go from bottom to top, you have to follow them backwards to get the hierarchy order:

CountryStateCity

De-normalized Dimension TablesIf a table represents a de-normalized hierarchy, there are no relationships between levels to help Report Studio figure out the hierarchy. For example:

If no special action is taken, then any facts in the State and Country sections (e.g. population) will be rolled up incorrectly. For example, if a state has 10 cities, then the when the state population is totaled, it will be 10 times too big, because the state population is duplicated for each city row. This is called “double counting”.To avoid this, modelers must set the Dimensional Information explicitly to specify what the hierarchy is, and which query items belong to each level in the hierarchy. Again, to help report authors understand, you should create a tree structure that reflects this. In this case though, each level is represented by a query item folder, rather than by a query subject. Each query item folder should contain all of the items that belong to that level. Put the identifier item(s) first – that’s what will be used most often.

When information is missing

Regardless if which case above is in effect, it’s best to always set the Dimensional information for every query subject. If a query subject contains only one level, specify its key, and tick the check box that says it’s unique. If you don’t, some strange things can sometimes happen, when Report Studio tries to supply the missing dimensional information on the fly from the database schema. (It currently does this using key and index information that is not visible to modellers.)


To ensure results that you and your users can understand, and that will not change from release to release, follow all modelling guidelines. In particular, always specify Dimension Information, even when it’s trivial.

Joining Fact Tables

This is a large subject, and much of it is beyond the scope of this document. A future document will provide more complete coverage. For now, we’ll just cover the basics.

It’s sometimes interesting to attempt to relate two or more fact tables by one or more common dimensions. Unfortunately, there are many problems with figuring out what users are looking for in these cases, and there is no industry consensus on how they should be handled.

Queries of this type are easy to understand only if all of the dimension levels used are meaningful for all columns in the report. For example, total sales of all products for the last 3 years, by month and by product line.

Here are some examples of queries that are not easy to understand:

Sales are recorded by day, but inventory is recorded by month, what does it mean to create a report that includes sales, inventory, and day?

sales and inventory dimensions that aren’t conformed

attributes from sales and inventory (Rare in dimensional sources)

It’s the modeler’s responsibility to help report authors avoid posing queries of this type.

Build Star Schema Models

Modelers should be careful to present a view that guides their users (especially QS users) away from building reports that violate these conditions. Techniques that can help:

Use the star schema approach. The view that you expose to modelers should always be a set of stars or snowflakes, each in its own folder or namespace. (Refer to the FM User Guide section on Star Schema Grouping.)

Never put two fact tables in the same folder or namespace.

In a fact table query subject, avoid exposing any query items that are not facts (measures with an aggregation rule). If necessary, expose them as a separate model query subject that looks like a dimension.

In each fact namespace, put only the dimensions that relate to it. Do not put dimensions anywhere else, such as in a common location.

Always give conformed dimensions the same name in each namespace where they appear. That’s the only way your users can tell that they are conformed.

If two fact tables have conformed dimensions, but different levels of granularity for that dimension, include for each fact table only the relevant levels.

If a dimension is based on a de-normalized table, for each fact table create a model query that omits query items for levels below the level of granularity for that fact table. For example, if inventory is only recorded at the month level, the time dimension for inventory should include years and months, but not days.


Use naming and grouping conventions that make it clear what is a fact (which can be aggregated), what is a dimension identifier (unique, usable for grouping), and what is an attribute (anything else).

Please refer the attached document for Framework Manager Modeling best practices.

3. Cognos Performance Tuning Tips

Please refer the attached document for performance tuning tips.

4. Recommendations on Cognos Reporting Architecture

Cognos 8 is a Web suite for creating and managing Managed (advanced) reports, Ad-hoc reports, Dashboards, Scorecrads, Anlaysis and Managing Events and Scheduling of Reporting Jobs. Cognos 8 is built on a services-based architecture allowing its components to be distributed across multiple servers in a three-zone architecture:

Presentation Zone – Provides presentation services to users who interface with a Cognos-based application from a web browser.

Application Zone – Contains the business and control logic for the applications and services.

Data Zone – Consists of content store and data servers.

Cognos’ flexible, three-tier architecture ensures fail-over protection and dynamic load balancing for high availability. The zones are separated by firewalls and Cognos user interfaces sit above the zones as shown in Figure 1.

Cognos components communicate with each other using the Cognos business intelligence (BI) Bus API protocol. The BI Bus API is an open, documented API based on Web Services Definition Language (WSDL) and Simple Object Access Protocol (SOAP).

Figure 1 depicts the three-zone Cognos architecture and user interfaces.


Presentation Zone The Presentation Zone contains the Cognos Application Firewall and one or more Cognos 8 gateways. The gateways support all web communications in Cognos. Several types of web gateways are supported, including CGI, ISAPI, apache-mod, and servlet.

Application Zone Within the Application Zone, the Cognos servers handle requests, such as reports and queries, and manage Cognos information. The Cognos server consists of a number of processes, each specializing in a specific task related to report management and operation. Some of these processes are written in Java to facilitate integration with external applications and others are written in C++ to facilitate performance.

Each Cognos installation includes a Dispatcher. The Dispatcher operates all Cognos services configured and enabled on the Cognos server, routes requests, and distributes configuration changes. The services managed by the dispatcher include the presentation service, batch report and report services, job and schedule monitoring service, and log service. The technology underlying the Cognos server consists of:

A java application server running the dispatcher java servlet.


A non-java component based on C++: The batch report and report services are native C++ applications that run as separate processes. The dispatcher communicates with the report service using a port acquired at run time.

Each Cognos installation also includes the Content Manager. The Content Manager stores and manages Cognos information. The Content Manager, which is a Java servlet, contains Cognos Access Manager, the primary security component of Cognos. The Content Manager servlet communicates with Cognos Access Manager through a Java Native Interface (JNI). The Cognos Access Manager can leverage an organization’s existing security server, such as Lightweight Directory Access Protocol (LDAP) authentication directory, to perform user authentication.


Figure 3 shows additional detail for the Content and Access Managers.

Data Zone The data zone contains the Content Store & Metric Store, which is an Oracle or IBM DB2 UDB relational database management system (RDBMS). The Content Store & Metric Store are used by the Content Manager to store all the Report Studio, Analysis Studio, Query Studio, Event Studio, Administration and Metrics Store information, managed by Cognos Connection or an existing enterprise portal. The Content Manager uses Java Database Connectivity (JDBC) API to access the Content Store & Metric Store.

The Content Store & Metric Store contain information about packages, folders, reports, saved results, directories, server configurations, and Cognos deployment.

Any query databases located in the data zone are accessed by the report services located in the Application zone access using native APIs or ODBC.


Component Recommendations This section provides specific recommendations for the selection and configuration of Cognos components.

Recommendation 1 Consider configuring Cognos Suite to use an alternate gateway that replaces the default CGI program in the Web server.

Rationale: All Web communication in Cognos 8 is through gateways residing on one or more Web servers. The Cognos 8 Installation and Configuration Guide states that the default CGI gateway can be used for all supported Web servers, but it delivers the slowest performance. Web server performance can be improved by configuring Cognos to use an alternate gateway replacing the default CGI program. Cognos 8 supports several types of gateways as alternatives to the CGI gateway.

Internet Server Application Programming Interface (ISAPI) - ISAPI can be used for the Microsoft Internet Information Services (IIS) Web server. It delivers faster performance for the IIS.

Apache_mod - The apache_mod gateway can be used with Apache Web servers or IBM HTTP servers.

Servlet - To use a servlet gateway, the Web server infrastructure must support servlets.

Of the alternatives for the Cognos gateway, the preferred choice for the applications running in the three tier Architecture appears to be the apache_mod configured with the IBM HTTP server. The servlet gateway does not seem to be a good choice as it appears this would require installing a servlet container in the Presentation Zone. However, before a final choice is made for the Cognos gateway, adequate performance testing should be conducted.

Recommendation 2 Install the Content Manager on a separate server for improved performance and locate it in the Data Zone for maximum security.

Rationale: As described in the Cognos 8 Installation and Configuration Guide, Cognos 8 can be configured with “Content Manager in the data tier for maximum security.” Installing the Content Manager on a separate server from the report servers can improve performance, availability, and capacity. According to the installation guide, Content Manager can be installed separately from the Cognos 8 report servers if the application data contains sensitive information. The Content Manager can also be installed on a separate server if the program is managing large volumes of data. Cognos scalability can be improved by increasing the size of the processor on which Content Manager is installed. Since the Content Manager is implemented as a Java servlet, a servlet container (e.g. WebSphere Application Server) would have to be installed to host the Content Manager on a separate server.


Recommendation 3 Configure Framework Manager to communicate through the Web server gateway.

Rationale: If a Web server other than Microsoft IIS is used, Cognos recommends that Framework Manager be configured to communicate through the Web server gateway. This eliminates the need to set up additional communications channels through the firewalls which separate Framework Manager, the Web server, and the Cognos server.

Administration and Security Recommendations This section provides recommendations for administration and security of the implementation of Cognos 8.

Recommendation 1Cognos 8 should use the security framework offered by the LDAP services for user authentication to enable an integrated authentication mechanism.

Rationale: Use of the an enterprise-wide LDAP services to perform user authentication for Cognos 8 application will enable a practical solution for user IDs and passwords for all the systems that need integration.

Recommendation 2 Use of role-based grouping to restrict users to certain metadata layers, individual reports, and data is strongly recommended. Rules that define roles or groups of users for authorization of report creation and viewing capabilities should be defined. The recommendation is to use the LDAP authentication server to define and maintain the authorization rules and explore creative ways to have the Cognos Access Manager read them.

Rationale: The definition and maintenance of roles or groups authorization rules for Cognos applications within the LDAP server, where users are authenticated with their IDs and passwords, will minimize the problems of multiple sets of user IDs and passwords and the need to maintain them in sync.

Recommendation 3Implementers should use great care to ensure that the basic security method of “least privileged” is enforced and users do not receive more permission than they are entitled.

Rationale: Cognos 8 can set permissions based on 3rd party credentials, such as a LDAP centralized authentication server. Cognos 8 also gives users combined permissions of all the groups for which they have membership. In effect, user permissions are based on the combined permissions given to groups they are members of from groups defined in the LDAP authentication server as well as Cognos 8 groups. .

Users should not be given more permissions than is required to perform the functions of the job and/or their clearance level. Without set policies and procedures on group membership and permissions, the security mode of “least privileged” cannot be verified


Recommendation 4All installations of Cognos 8 should use the highest encryption available, which in this product is 128 bit. Cognos 8 offers 56 bit encryption for data protection during transit as a base service, but it also offers 128 bit encryption as an add-on at an additional cost.

Rationale: It is a recommended practice that all applications secure traffic using 128 bit encryption as 56 bit encryption has been proven insecure in the past.

Recommendation 5 The Cognos 8 design should specify COTS configuration information to cross-reference the configuration settings necessary to maintain all hardware and software proposed in the technical architecture.

Rationale: A baseline configuration should be included in system designs to provide a starting point for the maintenance contractor.

Recommendation 6The Cognos 8 system should be backed up frequently and needs strong assurances of availability. This could include load balancing, active/passive failover modes, and redundant installs of all parts of Cognos 8.

Rationale: Cognos 8 based systems should be highly available to users, not affected by high traffic loads or faulty equipment. System design documentation should reflect periodic computer system backups of mission-critical data and archives to ensure the data is adequately preserved and protected against data loss and destruction.

Recommendation 7 Careful consideration on database security should be employed. Cognos does not have mechanisms in place to secure the back-end database from malicious or unintentional modification from the Cognos 8 front end. Therefore, the native security in the database should be used to restrict user’s access permissions. In addition, it is important to assign only trusted users to maintain the database.

Rationale: These assurances will protect the integrity and the health of the database. This recommendation will also ensure that users do not delete or corrupt entries or tables in the database in error.

Recommendation 8Cognos by default supports anonymous user access. Disabling this feature is strongly recommended.


Rationale: Support of anonymous users could potentially allow unauthorized users to view or modify sensitive data


cognos guidelines and best practices

Documents

query subjectsa query

query itemsa query item

set of query items

single query subject

use of cognos

relationshipswhile query

branches query subjects

cognos models