IBM Cognos Proven Practices: Durable Models

Best Practice for OEMs using IBM Cognos BI

Nature of Document: Proven Practice; Product(s):
Framework Manager; Area(s) of Interest: Modeling
Paul Maric
Strategic Project Advisor
IBM
Steve Newman
Technical Manager, ISV/ASL Solution Specialists
IBM

Skill Level: Intermediate

Date: 21 May 2010
(Updated 11 Aug 2011)

This document expands on the exiting Durable Models document and explains a
process that can be followed in 8.4.1 to create durable models.
View more content in this series

Introduction
Purpose
This document describes a process to ensure that changes to a Framework Manager
(FM) model's published packages and corresponding content in the Content Store
will continue to function in unison even as changes are made to the model.
Applicability
This practice applies to IBM Cognos 8 BI version 8.4.1 and IBM Cognos 10 BI,
specifically with Framework Manager models against non-OLAP sources, as well as
corresponding content created in the Content Store. This includes, but is not limited
to, Report Studio, Query Studio, Analysis Studio, and Event Studio content.
Exclusions and Exceptions
At the time of publish this technique does not apply to Dimensionally Modelled
Relational (DMR) models.
Copyright IBM Corporation 2010, 2011
IBM Cognos Proven Practices: Durable Models Best
Practice for OEMs using IBM Cognos BI

Trademarks
Page 1 of 11

developerWorks

ibm.com/developerWorks/

Overview
Background
When an Framework Manager model is created and published, the studios that use
the published package refer to components of the package for query generation
through an XML expression element in the format [namespace].[objectname], where
the objectname can be a query item (in [query subject].[query item] format), filter,
calculation, etc. Since the reference is to an object name and not an underlying or
unchanging identifier, care must be taken to ensure the object name used in the
studios does not change after they've been published.
The challenges with implementing this practice include,
Not knowing about this practice upon model or content creation, causing the
content created against the model to be non-durable.
Implementing this practice at model creation but not being able to control
the users' Content Language setting at the time of content creation. In IBM
Cognos BI versions before 8.4.1, the user's content language had to match
the model's design language at the time of content creation in order for the
practice to be fully implemented. This required a user to remember to change
their preferences each time they created content or to always have it set as the
design language. This may have been feasible for small development groups
but was not feasible for a larger audience and was not enforceable.
IBM Cognos BI v8.4.1 introduced a new FM model setting that forces newly created
content to refer to a model's design language, rather than the model language
corresponding to the user's content locale. In IBM Cognos 8.4.1 this setting is
not visible through the FM interface and must be set manually in the model's
underlying XML file, whereas in IBM Cognos 10 the setting can be enabled in the
properties pane for the project. The result is that new content from a durable model is
automatically durable.
However, existing content must also be made durable, which will be the focus for
most of the rest of this document. The entire process of model and content durability
is diagrammed and discussed.
Prerequisites
Assumptions made in this document include,
This document builds on the existing IBM Cognos Proven Practice document
titled IBM Cognos 8 Framework Manager - Durable Models, located at the
following URL. It is assumed the reader is familiar with this document.
http://www.ibm.com/developerworks/data/library/cognos/page60.html
There are references to other IBM Cognos products and utilities, as well as
3rd party applications in this document, and it is assumed these are thoroughly
understood, in terms of their selection for use, and the actual use of them. Each
IBM Cognos Proven Practices: Durable Models Best
Practice for OEMs using IBM Cognos BI

Page 2 of 11

ibm.com/developerWorks/

developerWorks

one has it's own supplied user guide and/or reference manual that needs to be
read and well understood. Diagnostic utilities are provided 'as is' and are not
supported as products, but rather are provided as examples of what can be
done with the IBM Cognos BI SDK.
The processes described here will update information in the IBM Cognos
BI Content Store, therefore it is highly recommended that this process be
tested in a non-production test or development environment, against a copy
of the production content store. It is also highly recommended that prior to the
validation and update process against production, a backup of the production
content store is taken, and all users are locked out of the system, so there is no
interference with the process.
This document makes references to specifications and content, which
refer generically to any of the content that is created through IBM Cognos
Connection. This includes Report Studio reports, Query Studio queries,
Analysis Studio analyses, Event Studio events, etc. It is assumed the reader is
familiar with all types of content that can be created from an FM model.
The Framework Manager model follows best practices in terms of layering,
meaning there are at least 2 layers of highest level namespaces, which ensures
that changes to the underlying data structures are isolated from the published
package layer. This document only applies to the Presentation layer. The
best practice is described in the FM help document Guidelines for Modeling
Metadata in the section titled Organizing the Model.

Model Durablity
The process to implement full model and content durability with IBM Cognos BI is
shown below, along with detailed descriptions of what's involved in the steps.
All of the following criteria must be met in order to have what is considered to be a
durable model:
1. There is a design language created for the model that is not the same as the
locales the users can choose from. For English, the design language is typically
English(Zimbabwe).
2. The design language name of all namespaces, query subjects, and query items
that are published in a package must never change after the package is initially
published. Other language names can change as needed, though.
3. The structure of a published package's namespace(s), query subjects, query
items, dimensions, shortcuts, etc, must not change over time. This structure is
stored in a specification's definition, along with the design language's names, so
this is the reason these must not change.
4. In IBM Cognos 8.4.1 the <fixIdsToDefaultLocale> element must exist in
model.xml. In IBM Cognos 10 the project level property Use Design Locale for
Reference ID must be set to true.
It the model is not durable, then the following changes must be done to make the
model durable:
IBM Cognos Proven Practices: Durable Models Best
Practice for OEMs using IBM Cognos BI

Page 3 of 11

developerWorks

ibm.com/developerWorks/

1. If the model does not already have a design language, then:

Add the necessary design language to the model and add it to the
languages of each package based on the model. Save and close the
model.
Using an XML or text editor, open the model.xml file and near the top of
the file, change the value of <defaultLocale>en</defaultLocale> to
<defaultLocale>en-zw</defaultLocale>.
2. For IBM Cognos 8.4.1, insert a blank line into the model.xml file under the
just modified <defaultLocale> element and add <fixIdsToDefaultLocale>true</
fixIdsToDefaultLocale> to the new blank line.
3. For IBM Cognos 10, set the project level property Use Design Locale for
Reference ID to a value of true, as depicted in the following screenshot.
Illustration 1: Screen image of the project properties pane in Framework
Manager showing the 'Use Design Locale for Reference ID' property

Once a model is made durable, packages based on the model will need to be republished and existing content checked for durability. Section 4 discusses how to
handle content durability.

Content Durablity
New Content Durability
All new content developed with IBM Cognos BI will be durable, as long as the model
is durable. Existing non-durable content can be made durable by appropriately
replacing the non-durable components of those specifications with durable
IBM Cognos Proven Practices: Durable Models Best
Practice for OEMs using IBM Cognos BI

Page 4 of 11

ibm.com/developerWorks/

developerWorks

components. Existing content is generally made durable over time as the content
gets updated for reasons other than durability.
Existing Content Durability
Existing Specifications are Durable?
A specification is defined as durable if all query item expressions in it refer to a valid
query item location/name within the model that corresponds to the model's design
language. If it's unclear whether this is the case, then proceed with the assumption
that at least some specifications are not durable.
Run Validation With Durable Model
Develop and run a process (manual, automated or mixture of both) that checks for
the validity of all specifications in the system, including user specific content. This can
be done through a variety of options including,
1. Having IBM Cognos Upgrade Manager to do bulk validation and prompt
handling.
2. Using diagnostic tools such as the Validate Report Specifications tool.
3. Individually through the studio validation option.
4. Using third party tools such as Motio PI.
Due to it's robustness, especially with respect to prompt handling, using IBM Cognos
Upgrade Manager may be the best option for validations. However, this decision
needs to be based on a variety of factors, including integration with the update
process (described later) and whether or not this process can be tied in with an
overall system upgrade. The pros and cons of each option are discussed later in this
document.
An Invalid specification is defined as one that returns the following message during
validation,
QE-DEF-0030 Expression parsing error.
QE-DEF-0359 The query contains a reference to at least one object
'[namespace].[query_subject].[query_item]' that does not exist.
A Valid specification is one that does not return this message during validation.
It is important to note that these definitions only pertain to this specific message and
that specifications can fail validation for other reasons but any other validation error
message would not pertain to this exercise.
If a validation fails, then the next step is described in the section Manual Update of
Missing Items. If the validation succeeds, the next step is described in the section
Run Validation With Design Language Only Durable Model.
IBM Cognos Proven Practices: Durable Models Best
Practice for OEMs using IBM Cognos BI

Page 5 of 11

developerWorks

ibm.com/developerWorks/

Manual Update of Missing Items

Specifications with non-existent components cannot be updated through an
automated process since there is nothing in the model to reference for an update.
Therefore these specifications must be updated or re-created manually using the
list of specifications that failed validation. The validation message indicates which
references are missing so this can be used to determine what needs to be re-added
to specifications.
If there are a few known changes or patterns of changes to the model that caused
invalid specifications to occur and there are many specifications that are affected, a
manual approach may not make sense. In this case, an automated update process
can be created to do this. For example, if the Query Item 'Product Name' (exposed in
a package) moved from [Presentation Layer].[Items].[Product Name] to [Presentation
Layer].[Products].[Product Name] then this could not be identified through model
XML mapping but the mapping feed into the update process could be enhanced to
include this manually or through further automation. The right balance of manual
effort and automation needs to be struck to make this update process work most
efficiently and effectively for your needs.
Once the changes have been made, the next step is to go back and run the
validation against a durable model as described in the section Run Validation With
Durable Model. This cycle should be repeated until all specifications are valid.
Run Validation With Design Language Only Durable Model
To create a design language only durable model, make a copy of the durable model
and remove all non-design languages from the copy. Save it as a temporary, testonly model. Do not overwrite the existing model as the only purpose of this
temporary model is for validation testing.
Publish the applicable package(s), making sure to remove old model versions, and
run a process that checks the validity of all specifications that were considered valid
in the earlier validation step. This is done by checking for the same error.
If the specifications that were previously valid are still valid the next step in the
process is described in the section titled Republish Durable Model.
If any previously valid specifications become invalid, proceed to the section titled
Automated Update (Optional).
Automated Update (Optional)
Non-durable specifications can be updated through an automated process that maps
non-durable components of the specification to the durable, design language value
by referencing the full durable model. The full durable model's XML can be traversed
IBM Cognos Proven Practices: Durable Models Best
Practice for OEMs using IBM Cognos BI

Page 6 of 11

ibm.com/developerWorks/

developerWorks

to identify this mapping and this process would need to be developed and tested
by you. Note that creating this type of automated mapping process may only make
sense if there are many objects in the model that need to be mapped or if it's difficult
to manually identify them. Otherwise a manually created mapping file may make
sense, which can then feed into a process that updates as many specifications as
needed.
The actual specification update can be done using a diagnostic tool called the
Dynamic Report Specification Updater (DRU), which can be obtained from the
following URL,
http://www.ibm.com/support/docview.wss?uid=swg24021248
The process that identifies non-durable specifications should also provide a list of
specifications and their associated 'missing' element references, so that list can feed
into this process.
Once this step is completed, the next step is described in the section titled Re-run
Validation With Design Language Only Durable Model.
Re-run Validation With Design Language Only Durable Model
Updated specifications are re-validated once for the following reasons,
To ensure all updated specifications are in fact now durable.
The specifications created in all other studios other than Report Studio (Query
Studio, Analysis Studio and Event Studio) have been known to have expression
references that are not fully qualified in the [namespace].[query subject].
[query item] format. This update process would not work for such a minispecification, so any of these mini-specifications will need to be identified and
managed through a manual fix. If a manual fix is cumbersome (typically due
to large numbers or getting access to user content), the pattern of expression
references in these mini-specifications can be analyzed and the update process
adjusted to accommodate this need.
If any of the updated specifications fail the re-validation, then follow then the next
steps are described in the section titled Manual Update of Missing Items. If all of
the updated specifications are successfully re-validated, the next step is described in
the section titled Republish Durable Model.
Manual Update of Missing Items
Report specifications that cannot be made durable through automation need to be
updated manually by opening the specification in the appropriate studio, making
the necessary changes and saving. Once all the necessary changes have been
made and saved, cycle back to the section titled Re-run Validation With Design
Language Only Durable Model.
IBM Cognos Proven Practices: Durable Models Best
Practice for OEMs using IBM Cognos BI

Page 7 of 11

developerWorks

ibm.com/developerWorks/

Republish Durable Model

Open the full durable model and republish to the content store with package
versioning turned off. Once this is done, the next step is described in the section titled
Re-run Validation With Durable Model.
Re-run Validation With Durable Model
All updated specifications (manual and automated) are revalidated one more time
to ensure they function against the actual durable model. If the process was done
correctly, there should be no failures but if there are those specifications should be
fed through the manual update process again to have them fixed.

IBM Cognos Proven Practices: Durable Models Best

Practice for OEMs using IBM Cognos BI

Page 8 of 11

ibm.com/developerWorks/

developerWorks

Illustration 2: Flow chart describing Content Durability section

IBM Cognos Proven Practices: Durable Models Best

Practice for OEMs using IBM Cognos BI

Page 9 of 11

developerWorks

ibm.com/developerWorks/

Appendix A
Validation Approaches
Below is a list of potential approaches to validating report specifications, including
some pros and cons for each approach.
Approach

Pros

Cons

Upgrade Manager

Mass handling
Not automatable
Prompt handling
Does not support My Folders
Workflow with an overall Cognos version
upgrade
Data and file validation available

Dynamic Report Specification Updater

diagnostic

Mass handling
Validation of data available
Easily modifiable and extensible

Complexity with integration needs

Lack of prompt handling
Single function

Individually through studios

Simplest option
Good when there are few specifications

No automation

3rd party tools such as Motio PI

Mass identification of invalid

specifications

Free options may not be extensible or

have validation output results

Automation Considerations
A few other considerations to have more automation in the process are,
1. Including user content in the process by moving it on a temporary basis to the
Public Folders area. User content can be accessed through the IBM Cognos BI
SDK using samples found in the IBM Cognos Support Technotes. An example
of such a sample is 'SDK Sample: How to view the content of all the "My Folder"
folders of all the accounts in the content store'. This sample was found in a
search of the IBM Cognos Support Technotes using the keywords 'SDK user
content'.
2. Since a package(s) is being changed in this process, each specification will
need to be updated and validated, which can be done through an automated
process. Doing a search of the IBM Cognos Support Technotes using the
keywords 'SDK update' will return several examples, including 'SDK sample to
update queries or reports after the package is republished' and 'SDK Sample to
update all report and query objects in all packages after a FM publish'.
3. It's possible that a more general purpose or batch driven update process would
be better than using the Dynamic Report Specification Updater (DRU). An
example SDK utility for this need could be 'SDK Sample to update the query
object in the Content Store', which will be returned in the search with the
keywords 'SDK update'.

IBM Cognos Proven Practices: Durable Models Best

Practice for OEMs using IBM Cognos BI

Page 10 of 11

ibm.com/developerWorks/

developerWorks

About the authors

Paul Maric
As a Strategic Project Advisor within the IBM Information Management
group, Paul specializes in working with ISV partners that utilize
the Cognos product line of Performance Management / Business
Intelligence applications.

Steve Newman
Steve Newman is a Technical Manager with the IBM Business Analytics
team focused on bringing ISV Partners solutions to market which embed
IBM Cognos and IBM SPSS products designed to assist the ISV's
customers make better fact based decisions.
Copyright IBM Corporation 2010, 2011
(www.ibm.com/legal/copytrade.shtml)
Trademarks
(www.ibm.com/developerworks/ibm/trademarks/)

IBM Cognos Proven Practices: Durable Models Best

Practice for OEMs using IBM Cognos BI

Page 11 of 11