COGNOS Reporting

Development Guidelines and Best Practices

For BBH Internal Use Only

Project Name: Cognos

Project ID: 13324
Prepared By: Steve Fiske
Department: Distributed Data Repository
Date: June 3, 2011
Version Number: 1.3

2008 Brown Brothers Harriman & Co. Confidential & Proprietary.

Not to be reproduced without the explicit consent of BBH & Co.
 Cognos Reporting Environment
Development Guidelines

Contents
Revision History......................................................................................................................3

Cognos Development Guidelines..................................................................................4

Purpose.....................................................................................................................................4
Overview....................................................................................................................................4
Product Usage.........................................................................................................................5

Framework Manager Model Development....................................................................7

Overview....................................................................................................................................7
Best Practices for Model Development............................................................................7

Report Development.....................................................................................................12
Overview..................................................................................................................................12
Best Practices for Report Development.........................................................................12

Appendix.........................................................................................................................15
Appendix A: Framework Manager Naming Standards................................................15
Appendix B: Report Studio Naming Standards...........................................................16
Appendix C: Cognos Reports Development Standards............................................17

Version 1.00 2 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

Revision History

Name Date Reason For Changes Version

Steve Fiske 10/14/2010 Create draft document 1.0
Updated Overview section with chart;
Steve Fiske 11/18/2010 1.1
enhanced Product Usage section
Enhanced Framework Manager Model
Steve Fiske 12/7/2010 Development and Report Development 1.2
sections
Incorporated Development Best
Steve Fiske 6/3/2011 Practices document provided by 1.3
Software By Design, Inc.

Version 1.00 3 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

Cognos Development Guidelines

Purpose
This document provides guidelines and best practices to be followed when developing new
reporting applications, or modifying existing reporting applications, using the Cognos suite of
Business Intelligence reporting tools.

Overview

The Cognos platform consists of a metadata modeling tool, Framework Manager, and various
Studios for reporting and analysis. Figure 1 is an illustration of the components that make up the
Cognos platform, and an overview of these components is given in the next section.

CognosDevelopment
Cognos DevelopmentPlatform
Platform

Cognos
Cognos
Framework
Framework
Manager CognosConnection
Cognos Connection
CORE
CORE Manager Web-based Portal
BANKING
BANKING (desktop)
(desktop) Web-based Portal
SYSTEMS
SYSTEMS

Query
Query
Studio
Studio
FUND
FUND Framework
Framework
ACCTG
ACCTG Manager
Manager
Model
Model Report
Report
Studio
Studio

BILLING
BILLING
SYSTEMS Metadata
Metadata
SYSTEMS Layer
Layer Analysis
Analysis
Studio
Studio
(Database
(Database
SEC Server)
Server)
SEC
LENDING
LENDING Event
Event
Studio
Studio

LDAP (WebServer)
(Web Server)
LDAP
*ANY*
*ANY*
*SOURCE*
*SOURCE*

Figure 1

Version 1.00 4 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

Product Usage

Framework Manager
Framework Manager is a metadata modeling tool that drives query generation for Cognos. A
model is a collection of metadata that includes physical information and business information for
one or more data sources. Cognos enables performance management on normalized and
denormalized relational data sources and a variety of OLAP data sources. When security and
multilingual capabilities are included, one model can serve the reporting, ad hoc querying, and
analysis needs of many groups of users around the globe.

Cognos Connection
Cognos Connection is the portal to Cognos, the Web-based reporting user interface, providing a
single access point to all corporate data. Cognos Connection is used to work with entries such as
queries, reports, analyses, agents, metrics, and packages. Cognos Connection is used to access
dashboards and reports, create shortcuts, URLs, portal pages, and can be personalized by the
individual user based on their preferences. Cognos Connection provides a centralized facility for
developers and power users to access the tools that allow them to create and run reports, set up
and run agents and schedules, and create distribution rules. NOTE: if a customized interface is
used instead of Cognos Connection, access to all the documented features may not be available.

Query Studio
Query Studio is the reporting tool for creating simple queries and reports in Cognos. A casual or
novice user can use Query Studio to create self-serve reports that answer simple business
questions. With minimal steps, users can view data, author basic reports, change the report layout,
filter and sort data, add formatting, and create charts.

Report Studio
Report Studio is ideal for users who need quick and easy report creation and formatting
capabilities, without requiring professional authoring skills. Report Studio contains the traditional
Professional authoring mode as well as the Express authoring mode. To meet the needs of both
regular report authors and financial report authors, Report Studio provides tailored user interfaces
that contain reporting features relevant to these roles. Access to each authoring mode is
determined by the permissions given to the user based on their assigned role.

Analysis Studio
Managers and analysts use Analysis Studio to better understand their business and to get answers
to questions that they have about their business. Users can quickly and easily perform analysis to
get to the what and why behind an event or action so that they can improve business performance.
With analysis, it is possible to see trends and understand anomalies or variances that may not be
evident with other types of reporting. Analysis Studio users can easily focus on what is important
even with large volumes of dimensional data.

Event Studio
Event Studio is the notification tool used to alert decision-makers in the organization of events as
they happen, so that they can make timely and effective decisions. Event Studio can be used to
Version 1.00 5 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

create agents that monitor status changes, priority customers, and organizations data to detect
occurrences of business events, or any other factor that is important to the business. Specify the
event condition, or a change in data, that is important, and when an agent detects an event, it can
perform tasks such as sending an email, adding information to the portal, and running reports.

Version 1.00 6 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

Framework Manager Model Development

Overview
In order to develop an efficient and easily maintainable Framework model, there are a number of
general best practices that should be followed. This information is not intended to be a
replacement for formal training or for the product documentation, but instead meant to provide
supplemental guidelines for development based on the specific characteristics of the BBH
reporting environment.
Best Practices for Model Development
Framework Project Organization
Why Should The Project Be Organized?
The goal of putting some thoughtful organization and design theory into a Framework Project is
to build a Model that is flexible to business needs, durable to changes, and easy to
understand as the Model grows. With a little extra effort and planning up front,
downstream changes can minimize upstream impact, saving more time and effort than was
originally put into building the model. Other resources will be able to open the model and
understand it's structure and layout quickly, enabling them to work confidently on the
project. Security can be consistently applied to the same layer in every project, taking out
the guess work and decreasing administrative overhead or time taken to troubleshoot an
issue. These are just some examples of the many benefits we hope can be realized when
these Framework Modeling Standards and Best Practices are used in conjunction with the
rest of the Cognos 10 Platform Standards and Best Practices.

Framework Metadata Modeling - Four Layer Approach

Good Framework Manager Modeling consists of creating three different namespaces (or layers)
within the project. These are the Data layer, Logical layer, and Business View layer.
Where necessary, a fourth layer can also be included for Dimensions (DMRs). So in the
Framework project we would have:
Data (Foundation) View
Logical (Transformation) View
Business (Presentation) View
Dimensional View
Each layer has a specific function and set of modeling activities. Generally, the layers build upon
one another, with the data layer being the foundation of the model. The typical work flow
of creating a Framework Project would be: Create the Data View, create the Logical View,
create the Dimensional View, and finally the Business View.
Other areas, such as packages and connections are also important, but fall outside of the layers.
Many of the best practices can be thought of in terms of what development activities should or
should not be performed in each of the layers.

Data (Foundation) Layer

The data layer, also called the import layer, contains the data source query subjects, based directly
on the underlying database objects. This layer is used to access the actual tables, views, and stored
procedures in the database. Add joins, cardinality and determinants at this level. Cardinality, the
Version 1.00 7 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

definition of how joins should behave, is critical to a well developed model and can be confusing,
even to seasoned veterans. The only other modification at this layer is to change column
properties so that identifiers, facts, and attributes are defined correctly.
Additionally, alias tables (alias shortcuts in FM) can be added here as well, and should be properly
marked as such. It is recommended you choose an existing table and create an "Alias Shortcut"
rather than re-importing the table again and renaming it.

Expect 20 to 40 percent of the model development to take place in the data layer.

Logical (Transformation) Layer

The logical layer adds the bulk of the meta-data to the model, and consequently is where most of
the work is likely to occur. It provides business context and understanding to the data objects. The
"query subjects" are imported from the Data (Foundation) View. These newly created query
subjects in the Transformation View layer are then brought directly into the Business View layer
after changing the technical table/field names to business names. Tasks include but are not limited
to:
Organizing elements into logical query subjects. This may mean combining elements from
multiple tables, as in a snowflake dimension.
Renaming element names, including descriptions and tooltips, and adding multiple
language definitions if needed. Assign standardized and business-defined terms to the
database columns, giving them business context.
Add calculations, and filters including stand-alone filters, embedded filters and security-
based filters. Base these on the underlying data layer objects to make them less susceptible
to errors when copying and reusing the query subject.
Arrange query subject items in a user-friendly manner. Make use of folders to group
similar items, or when there are too many items. I suggest 12 or fewer objects per folder,
although more can be used when the logical breakout calls for it. For example, if there are
many dates in a query subject, it might be more intuitive to have all the dates in a single
large folder, than to try to subdivide each into smaller, random folders. Arrange the
contents of the folder in an intuitive manner, such as alphabetic, or with the most
commonly used items at top. HINT: It can be useful to use the Reorder command
available within FM for this purpose.
Assign output formats and usages to the reporting elements. This is easier if you create a
small folder of trivial calculations, used only to provide standardized object format
templates. The formats can easily be copied to target items by multi-selecting, and
dragging the topmost format through the list.
Add prompts, including cascading prompts, and prompt-based calculations.
Columns that will not be used in the Studios for reporting should be removed from the
Transformation View. They serve no purpose and may slow query performance.

Roughly 50 to 70 percent of the modeling work occurs in this section.

Business (Presentation) Layer

The importance of making information easy for report writers to use is frequently underestimated,
but is a critical component to driving user adoption. Fortunately, this can be a simple step. The
Version 1.00 8 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

presentation layer is used only as an organization structure in order to make it easier for report
writers to more easily find their needed information. This layer includes only shortcuts to existing
items in the logical layer, plus organization items such as folders and namespaces.
For example, create a namespace called Orders and include shortcuts to the ten or twenty
relevant query subjects, out of perhaps a hundred or more query subjects in the logical layer.
Also include shortcuts to relevant filters. Commonly used query subjects (such as Items or
Customers) will appear in multiple areas. Rename the shortcuts to something which provides
helpful business context.
For organizing major groupings, you can use either folders or namespaces. However be aware
that namespace names must be unique, and that items within a namespace must likewise be
unique. So, if you use folders for your major groupings, you cannot have a shortcut named
Items in more than one folder. You must rename them to unique names, such as Order
Items. For this reason in particular, it is generally preferred to use separate namespaces.
There may actually be a few Business Views in your model. There will typically be different
views of relational data, and also views of dimensional data, depending of course on business
and user requirements.

The presentation layer takes approximately 10% of the overall model design effort.

Dimensional Layer
The dimensional layer is required only for models which include dimensionally modeled data.
Leaving aside the trivial situations where cubes are simply imported into the model, this includes
dimensionally modeled relational data (DMR).
Dimensions in Framework Manager can be used in Studios, can enable drill down functionality in
reports, and can provide "member" functions in Report Studio.
Packages should be created with only DMRs, or only with Relational Query Subjects.
Several DMRs may be created from a single query subject, so a separate namespace keeps
DMRs better organized.
The Framework Manager model is simply just easier to understand when organized with a
separate Dimensional View layer.
In this layer, no joins should be necessary because each DMR refers back to one or several query
subjects in the Transformation View layer, which should contain all the necessary joins
Specifically, this is for creating Dimensional and Measure Dimension Query subjects. Much like
the presentation layer, this layer also is built upon the logical layer, which leverages the effort put
into that layer. Apply the element renaming, descriptions, tooltips in the logical layer, and they can
be reused in the dimensional layer, with some help from the search tool.
Finally, note that when you are creating the final package, you should hide the data and logical
layers so that the user will only see the presentation and/or dimensional layers.

General Guidelines
Size
While there is no size limit, a model that contains too many subject areas will be unwieldy
and difficult to maintain. It is suggested that models be limited to logical subject areas
wherever possible.
Version 1.00 9 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

Packages generated from the model should also be limited to logical subject areas.
Otherwise, excessive wait times will occur when users open a package for querying.
Import only what is needed rather than everything in the underlying database.
Structure
When importing through the Metadata Wizard, do not select option to auto-join unless
physical schema has been fully defined on the database.
Renaming of physical tables and columns should be avoided as it may lead to confusion if
the object names in the physical model do not match the database.
Sources should be
Namespace vs. Folder
Namespaces must be unique, and are used in the internal reference paths for query
subjects. Folders are not used in this manner. Changing Namespaces will break your
reports, because the reference path to the query subject will change. If you don't have an
abundance of reports, or can put this change in when users are typically not in the system,
you can correct the reports that are broken by the change. The main thing to consider is
that, if you decide later to re-organize the query subjects by moving them between
namespaces, then your reports will break, whereas moving them between folders within a
namespace will not break the reports.
Folders are much simpler than namespaces. They are purely for organizational purposes
and does not impact object IDs or your content. You can create folders to organize objects
by subject or functional area. This makes it easier for you to locate metadata, particularly
in large projects. The main drawback of folders is that they require unique names for all
query subjects, dimensions, and shortcuts. Therefore, they are not ideal for containing
shared objects.
Miscellaneous
Develop and enforce consistent naming standards and conventions (i.e. Amt for amount,
Ind for indicator. Another example is Amt fields should be numeric, Ind should have
a value of Y,N or 1,0.)
Whenever possible, use unmodified SQL (select * from Table Name) to retrieve the
table information. If you modify the SQL code or add a filter or a calculation to the data
subject, it eliminates Framework Managers meta-data caching capabilities. This means that
Cognos 8 will validate the query subject at report run time, adding overhead to the report
load time. In some circumstances, this may be worth the trade-off, but should be avoided
when possible.
Run Model Advisor to identify any issues with the model, such as facts identified by
cardinality, query subjects that join to themselves, query subjects with multiple
relationships, determinants that conflict with relationships, query subjects that can behave
as facts or dimensions, factors that will override the minimized SQL setting, embedded
calculations that use the calculated aggregation type, query subjects that can cause a
metadata caching conflict
Physical view should not be altered all changes should be made to the business view
including security. Changes that should minimize the impact on existing reports are those
done on calculations, security or descriptions of Query Items. Changes to the actual
naming conventions will impact existing reports and require the author to modify them.

Version 1.00 10 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

When changing any part of a model check to see what reports will be impacted by the
change, by using the Find report dependencies task in Framework Manager.
Developing well thought out object names in the business view within the model are very
important, especially once report writing begins, because they are difficult to change
without invalidating existing reports.

Version 1.00 11 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

Report Development
Overview
Business Intelligence reporting in Cognos differs significantly from Hyperion in a number of areas.
These guidelines and best practices are provided in order to assist users and developers in the
transition from Hyperion to the Cognos Reporting environment. As mentioned above, this
information is not intended to be a replacement for formal training or for the product
documentation, but instead meant to provide supplemental guidelines for development based on
the specific characteristics of the BBH reporting environment.

The data is accessible for development of queries and reports through centralized metadata,
modeled in Framework Manager (see above), and exposed in the various studios as a Package
containing the data elements available based on a users rights and permissions. The query, report,
and dashboard objects are developed and stored within the Cognos Connection web-based portal.

Best Practices for Report Development

Set report preferences to Preview with no data or Preview with limited data during initial
development in order to avoid querying the data source each time a change is made.
When developing a new report, assign a name and save the report prior to building the layout.
Local Processing. In all queries, turn local processing off whenever possible - i.e. set up for
Database Processing only - this forces work to be done in the database and if we've defined
reporting tables properly will always be viable option.
Auto Summarization. In all queries which are putting one record out in the report per
database record, always turn the Auto Summarize option for the query to No (default is Yes).
This can make a huge difference to query performance and complexity when picking up lots of
fields, as otherwise the SQL consists of a mass of SUM() and MAX() and then GROUP BY
for all dimensions/attributes - unnecessarily so. Again, in the majority of cases, we'll be using
one record per output row so this is generally going to work well.
Setting Sizes - especially heights. Don't try and control sizes when you don't need to -
particularly heights. It can be good practice to control the width of various columns
sometimes to create a level of symmetry and in particular to control widths when headings
have multiple words, or in tables that need to mutually line up - but in general web based apps
should be allowed to do what they need to do to fit the output window (or paper) as best they
can. Controlling heights is particularly messy and should rarely be necessary in multi row
reports. There WILL always be a better way with the powerful alignment, padding and margin
settings.
Controlling when objects appear or are hidden. Quite often it is necessary to control when an
object appears and when it doesn't. If this is a simple yes or no, always use the rendering
control rather than conditional blocks/formatting - much simpler and less hassle within report
studio. If the display should be on 'no' create a second variable. Conditional blocks are
generally more relevant when trying to remove a column altogether so that when not
displayed there is no width (typically drill through hyperlinks).
Version 1.00 12 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

Report Expressions vs. Query Expressions - report expressions are quite limited in terms of
functionality and construction - generally better if constructing something to display to do it in
the query and use the query variable.
Tables (Report Studio table control) are your friend. You really need to be comfortable with
tables within tables within tables as a way of laying out reports which align multiple elements
with the developer really in control. They can go anywhere - in list columns, in headings, on
the background (and list controls should generally always sit within a table cell so you can add
items above and below the list). There is no overhead with tables and they are a great way of
keeping control of output if used well. Additionally, tables can be used in single cut and paste
operations to replicate their content - table cells etc can't. And remember, when working
within table cells, always set the vertical and horizontal alignment the cell to control what
happens if the objects within the cell don't fill it - again, take control of the output.
Set formatting at the highest level. If you do have to override the default formats in a report
and in list controls etc, do so at the highest possible level (e.g. table cell rather than every text
item in the cell, and via the List Columns Body Style and List Columns Title Style options
rather than for each individual column or heading) - also includes padding, alignment, border
settings as well as color and font etc. This simplifies your life as a developer, means that if new
objects are added or columns included they inherit the correct style and will keep the size of
the html passed into browsers to minimum.
Keep it simple! Two basic elements here - on the data/query side put the complexity into the
actual data if the complexity really is essential, or by second choice into the model, but keep it
out of the reports; and on the report pages - avoid if possible, the use of JavaScript or other
complex solutions as they will be difficult to maintain and will almost certainly be a problem
during Cognos upgrades.
When writing reports in Report Studio, Validate early and validate often. When a warning
shows up, deal with it. Warning will allow a report to run, but you may get unexpected results,
especially if you are mixing dimensional and relational functions.
Remember which functions are for Relational reports and which are for Dimensional reports
and dont use the wrong function set. Again, you may get results, but they can be unexpected.
It is always better to not return data than to return incorrect data.
Keep the number of queries in each report to a minimum. The more the number of queries in
the report, the more negative impact it is going to have on the performance.
Use a standard report template for any new report. The template should have the header and
footer along with company logo.
Use Relational reports for most detail and list style reports. Relational reports are also the
standard when reporting against data marts, even dimensionally modeled star schema designs.
Avoid complex cross-tabs in Relational reports.
Use Dimensional reports for most crosstab and summary reports. Dimensional reports are the
standard when reporting against OLAP data sources and DMR models in Framework
Packages. Do not try to do detail lists in Dimensional reports.
Avoid combining relational and dimensional data in the same report - it is acceptable in some
cases to mix these two sources in a single report provided you do not attempt to join them
together in any manner. For instance, you cannot query a dimensional query and relational
query and then attempt to build a new third query defined as a join between these two.

Version 1.00 13 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

Appendix
Appendix A: Framework Manager Naming Standards

Naming Standard for Alias Tables: "OriginalTableName_ A"

Naming Standard for Tables: "OriginalTableName_ T"
Naming Standard for Views: "OriginalTableName_ V"
Naming Standard for Stored Procedures: "OriginalTableName_ SP"
Naming Standard for Materialized Views: "OriginalTableName_ MV"

Version 1.00 14 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

Appendix B: Report Studio Naming Standards

Report Query: "qry_QueryName"
Report Prompt Query: "qry_Pmt_QueryName"
Report Page: "rep_PageName"
Condition Variable: "v_VariableName"
Report Prompt: "p_PromptName"

Version 1.00 15 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

Appendix C: Cognos Reports Development Standards

Font: Default font used in Report Studio
Size: Regular text and Parameter headings default (10 pt); Page Title (12 pt).
Case: Fields, column headings, and titles First letter in uppercase.
Weight: Fields, column headings, and titles all bolded.
Style: Default style used in Report Studio.
Underlining: Page title underlined.

Version 1.00 16 BBH & Co. Confidential & Proprietary

DRAFT
 Cognos Reporting Environment
Development Guidelines

Version 1.00 17 BBH & Co. Confidential & Proprietary

DRAFT