Cognos Model Durability

© Copyright IBM Corporation 2010, 2011 TrademarksIBM Cognos Proven Practices: Durable Models BestPractice for OEMs using IBM Cognos BI

of 11

IBM Cognos Proven Practices: Durable ModelsBest Practice for OEMs using IBM Cognos BINature of Document: Proven Practice; Product(s):Framework Manager; Area(s) of Interest: Modeling

Paul MaricStrategic Project AdvisorIBM

Steve NewmanTechnical Manager, ISV/ASL Solution SpecialistsIBM

Skill Level: Intermediate

Date: 21 May 2010(Updated 11 Aug 2011)

This document expands on the exiting Durable Models document and explains aprocess that can be followed in 8.4.1 to create durable models.

View more content in this series

IntroductionPurpose

This document describes a process to ensure that changes to a Framework Manager(FM) model's published packages and corresponding content in the Content Storewill 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 ascorresponding content created in the Content Store. This includes, but is not limitedto, 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 ModelledRelational (DMR) models.

http://www.ibm.com/legal/copytrade.shtml

http://www.ibm.com/developerworks/ibm/trademarks/

http://www.ibm.com/developerworks/data/library/cognos/cognosprovenpractices.html

developerWorks® ibm.com/developerWorks/

IBM Cognos Proven Practices: Durable Models BestPractice for OEMs using IBM Cognos BI

of 11

OverviewBackgroundWhen an Framework Manager model is created and published, the studios that usethe published package refer to components of the package for query generationthrough an XML expression element in the format [namespace].[objectname], wherethe 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 orunchanging identifier, care must be taken to ensure the object name used in thestudios 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 thecontent created against the model to be non-durable.

• Implementing this practice at model creation but not being able to controlthe users' Content Language setting at the time of content creation. In IBMCognos BI versions before 8.4.1, the user's content language had to matchthe model's design language at the time of content creation in order for thepractice to be fully implemented. This required a user to remember to changetheir preferences each time they created content or to always have it set as thedesign language. This may have been feasible for small development groupsbut 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 createdcontent to refer to a model's design language, rather than the model languagecorresponding to the user's content locale. In IBM Cognos 8.4.1 this setting isnot visible through the FM interface and must be set manually in the model'sunderlying XML file, whereas in IBM Cognos 10 the setting can be enabled in theproperties pane for the project. The result is that new content from a durable model isautomatically durable.

However, existing content must also be made durable, which will be the focus formost of the rest of this document. The entire process of model and content durabilityis diagrammed and discussed.

PrerequisitesAssumptions made in this document include,

• This document builds on the existing IBM Cognos Proven Practice documenttitled “IBM Cognos 8 Framework Manager - Durable Models”, located at thefollowing 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 as3rd party applications in this document, and it is assumed these are thoroughlyunderstood, in terms of their selection for use, and the actual use of them. Each

http://www.ibm.com/developerworks/data/library/cognos/page60.html

ibm.com/developerWorks/ developerWorks®


of 11

one has it's own supplied user guide and/or reference manual that needs to beread and well understood. Diagnostic utilities are provided 'as is' and are notsupported as products, but rather are provided as examples of what can bedone with the IBM Cognos BI SDK.

• The processes described here will update information in the IBM CognosBI Content Store, therefore it is highly recommended that this process betested in a non-production test or development environment, against a copyof the production content store. It is also highly recommended that prior to thevalidation and update process against production, a backup of the productioncontent store is taken, and all users are locked out of the system, so there is nointerference with the process.

• This document makes references to specifications and content, whichrefer generically to any of the content that is created through IBM CognosConnection. This includes Report Studio reports, Query Studio queries,Analysis Studio analyses, Event Studio events, etc. It is assumed the reader isfamiliar 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 ensuresthat changes to the underlying data structures are isolated from the publishedpackage layer. This document only applies to the Presentation layer. Thebest practice is described in the FM help document “Guidelines for ModelingMetadata” in the section titled “Organizing the Model”.

Model DurablityThe process to implement full model and content durability with IBM Cognos BI isshown 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 adurable model:

1. There is a design language created for the model that is not the same as thelocales the users can choose from. For English, the design language is typicallyEnglish(Zimbabwe).

2. The design language name of all namespaces, query subjects, and query itemsthat are published in a package must never change after the package is initiallypublished. Other language names can change as needed, though.

3. The structure of a published package's namespace(s), query subjects, queryitems, dimensions, shortcuts, etc, must not change over time. This structure isstored in a specification's definition, along with the design language's names, sothis is the reason these must not change.

4. In IBM Cognos 8.4.1 the <fixIdsToDefaultLocale> element must exist inmodel.xml. In IBM Cognos 10 the project level property Use Design Locale forReference ID must be set to true.

It the model is not durable, then the following changes must be done to make themodel durable:



of 11

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 themodel.

• Using an XML or text editor, open the model.xml file and near the top ofthe 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 thejust 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 forReference ID to a value of true, as depicted in the following screenshot.Illustration 1: Screen image of the project properties pane in FrameworkManager showing the 'Use Design Locale for Reference ID' property

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

Content DurablityNew Content Durability

All new content developed with IBM Cognos BI will be durable, as long as the modelis durable. Existing non-durable content can be made durable by appropriatelyreplacing the non-durable components of those specifications with durable



of 11

components. Existing content is generally made durable over time as the contentgets 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 validquery item location/name within the model that corresponds to the model's designlanguage. If it's unclear whether this is the case, then proceed with the assumptionthat 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 forthe validity of all specifications in the system, including user specific content. This canbe done through a variety of options including,

1. Having IBM Cognos Upgrade Manager to do bulk validation and prompthandling.

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 CognosUpgrade Manager may be the best option for validations. However, this decisionneeds to be based on a variety of factors, including integration with the updateprocess (described later) and whether or not this process can be tied in with anoverall system upgrade. The pros and cons of each option are discussed later in thisdocument.

An Invalid specification is defined as one that returns the following message duringvalidation,

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 andthat specifications can fail validation for other reasons but any other validation errormessage would not pertain to this exercise.

If a validation fails, then the next step is described in the section Manual Update ofMissing Items. If the validation succeeds, the next step is described in the sectionRun Validation With Design Language Only Durable Model.



of 11

Manual Update of Missing Items

Specifications with non-existent components cannot be updated through anautomated process since there is nothing in the model to reference for an update.Therefore these specifications must be updated or re-created manually using thelist of specifications that failed validation. The validation message indicates whichreferences are missing so this can be used to determine what needs to be re-addedto specifications.

If there are a few known changes or patterns of changes to the model that causedinvalid specifications to occur and there are many specifications that are affected, amanual approach may not make sense. In this case, an automated update processcan be created to do this. For example, if the Query Item 'Product Name' (exposed ina package) moved from [Presentation Layer].[Items].[Product Name] to [PresentationLayer].[Products].[Product Name] then this could not be identified through modelXML mapping but the mapping feed into the update process could be enhanced toinclude this manually or through further automation. The right balance of manualeffort and automation needs to be struck to make this update process work mostefficiently and effectively for your needs.

Once the changes have been made, the next step is to go back and run thevalidation against a durable model as described in the section Run Validation WithDurable 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 modeland remove all non-design languages from the copy. Save it as a temporary, test-only model. Do not overwrite the existing model as the only purpose of thistemporary model is for validation testing.

Publish the applicable package(s), making sure to remove old model versions, andrun a process that checks the validity of all specifications that were considered validin 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 theprocess is described in the section titled Republish Durable Model.

If any previously valid specifications become invalid, proceed to the section titledAutomated Update (Optional).

Automated Update (Optional)

Non-durable specifications can be updated through an automated process that mapsnon-durable components of the specification to the durable, design language valueby referencing the full durable model. The full durable model's XML can be traversed



of 11

to identify this mapping and this process would need to be developed and testedby you. Note that creating this type of automated mapping process may only makesense if there are many objects in the model that need to be mapped or if it's difficultto manually identify them. Otherwise a manually created mapping file may makesense, which can then feed into a process that updates as many specifications asneeded.

The actual specification update can be done using a diagnostic tool called theDynamic Report Specification Updater (DRU), which can be obtained from thefollowing URL,

http://www.ibm.com/support/docview.wss?uid=swg24021248

The process that identifies non-durable specifications should also provide a list ofspecifications and their associated 'missing' element references, so that list can feedinto this process.

Once this step is completed, the next step is described in the section titled Re-runValidation 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 expressionreferences that are not fully qualified in the [namespace].[query subject].[query item] format. This update process would not work for such a mini-specification, so any of these mini-specifications will need to be identified andmanaged through a manual fix. If a manual fix is cumbersome (typically dueto large numbers or getting access to user content), the pattern of expressionreferences in these mini-specifications can be analyzed and the update processadjusted to accommodate this need.

If any of the updated specifications fail the re-validation, then follow then the nextsteps are described in the section titled Manual Update of Missing Items. If all ofthe updated specifications are successfully re-validated, the next step is described inthe section titled Republish Durable Model.

Manual Update of Missing Items

Report specifications that cannot be made durable through automation need to beupdated manually by opening the specification in the appropriate studio, makingthe necessary changes and saving. Once all the necessary changes have beenmade and saved, cycle back to the section titled Re-run Validation With DesignLanguage Only Durable Model.




of 11

Republish Durable Model

Open the full durable model and republish to the content store with packageversioning turned off. Once this is done, the next step is described in the section titledRe-run Validation With Durable Model.

Re-run Validation With Durable Model

All updated specifications (manual and automated) are revalidated one more timeto ensure they function against the actual durable model. If the process was donecorrectly, there should be no failures but if there are those specifications should befed through the manual update process again to have them fixed.



of 11

Illustration 2: Flow chart describing Content Durability section



of 11

Appendix A

Validation Approaches

Below is a list of potential approaches to validating report specifications, includingsome pros and cons for each approach.

Approach Pros Cons

Upgrade Manager Mass handlingPrompt handlingWorkflow with an overall Cognos versionupgradeData and file validation available

Not automatableDoes not support My Folders

Dynamic Report Specification Updaterdiagnostic

Mass handlingValidation of data availableEasily modifiable and extensible

Complexity with integration needsLack of prompt handlingSingle function

Individually through studios Simplest optionGood when there are few specifications

No automation

3rd party tools such as Motio PI Mass identification of invalidspecifications

Free options may not be extensible orhave 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 thePublic Folders area. User content can be accessed through the IBM Cognos BISDK using samples found in the IBM Cognos Support Technotes. An exampleof 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 asearch of the IBM Cognos Support Technotes using the keywords 'SDK usercontent'.

2. Since a package(s) is being changed in this process, each specification willneed to be updated and validated, which can be done through an automatedprocess. Doing a search of the IBM Cognos Support Technotes using thekeywords 'SDK update' will return several examples, including 'SDK sample toupdate queries or reports after the package is republished' and 'SDK Sample toupdate 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 wouldbe better than using the Dynamic Report Specification Updater (DRU). Anexample SDK utility for this need could be 'SDK Sample to update the queryobject in the Content Store', which will be returned in the search with thekeywords 'SDK update'.

http://public.dhe.ibm.com/software/data/cognos/documentation/docs/en/8.4.1/ug_upgr_mngr.pdf





of 11

About the authors

Paul Maric

As a Strategic Project Advisor within the IBM Information Managementgroup, Paul specializes in working with ISV partners that utilizethe Cognos product line of Performance Management / BusinessIntelligence applications.

Steve Newman

Steve Newman is a Technical Manager with the IBM Business Analyticsteam focused on bringing ISV Partners solutions to market which embedIBM Cognos and IBM SPSS products designed to assist the ISV'scustomers make better fact based decisions.

© Copyright IBM Corporation 2010, 2011(www.ibm.com/legal/copytrade.shtml)Trademarks(www.ibm.com/developerworks/ibm/trademarks/)

http://www.ibm.com/legal/copytrade.shtml

http://www.ibm.com/developerworks/ibm/trademarks/

Cognos Model Durability

Documents

Transcript of Cognos Model Durability