CDM Best Practice

IBM COGNOS DISCLOSURE
MANAGEMENT 10.2 – BEST Best Practices ver.

1.0
PRACTICES DOCUMENT VER. 1.0
This document is designed to provide insights to some commonly used best

practices as applied to IBM Cognos Disclosure Management version 10.2.
1|Page
IBM Cognos Disclosure Management 10.2 – Best Practices Document ver. 1.0 2012
Contents
Architecture/Installation:.............................................................................................................................. 4
1. Click Once Deployment. ................................................................................................................ 4
2. Application Server Deployment. ................................................................................................... 4
3. CDM Deployment on Multiple Environments............................................................................... 5
4. CDM Client Deployment ............................................................................................................... 6
Security: ........................................................................................................................................................ 7
5. Workflow Object Security ............................................................................................................. 7
6. Change Reference and Object Security ........................................................................................ 7
7. Password Complexity .................................................................................................................... 7
8. Automatic Login ............................................................................................................................ 8
9. Importing Groups from AD with Auto-Registrable option ............................................................ 8
Workflow: ..................................................................................................................................................... 9
10. Bulk Workflow Operation ......................................................................................................... 9
11. Template Workflow Design....................................................................................................... 9
Report and Object Management: ................................................................................................................. 9
12. Importing Objects ..................................................................................................................... 9
13. Deleting Bulk Objects .............................................................................................................. 10
14. Object Hierarchy and Delete Behaviour ................................................................................. 10
15. PDF Objects ............................................................................................................................. 10
16. Microsoft PowerPoint Objects ................................................................................................ 11
17. Microsoft Excel Objects: External Links .................................................................................. 13
18. Microsoft Excel Objects: Reserved Ranges ............................................................................. 13
Example: Var_Consolidate_Area .......................................................................................................... 8
19. Microsoft Excel Objects: Add-in Mode ..................................................................................... 8
20. Microsoft Excel Objects: Using Now(), Workday () formulas in Microsoft Excel calculations . 8
21. Microsoft Excel Objects: Image Range Variables (##IRS/##IRE) ............................................... 8
22. Resolving Microsoft Excel Range Variables in Microsoft Word Objects ................................... 8
23. Page Setup and Office Theme Fonts ....................................................................................... 10
24. Object Properties: Break Type ................................................................................................ 10
25. Variable Chaining .................................................................................................................... 10
2|Page
26. Working with Microsoft Excel objects and HFM SmartView formulas ................................... 12
27. Automatic Refresh of HFM SmartView formulas .................................................................... 12
Data Source/Query Management:.............................................................................................................. 13
28. TM1 Data Source vs. TM1 Perspective in CDM ....................................................................... 13
29. Cognos Controller in CDM....................................................................................................... 13
30. Cognos For Microsoft Office/Cognos Analysis for Microsoft Excel in CDM ............................ 14
31. Cognos For Microsoft Office Search functionality and Office 2003........................................ 14
32. Cognos For Microsoft Office behaviour with multiple Microsoft PowerPoint Instances ....... 14
33. Editing External Microsoft Excel File Structure ....................................................................... 15
34. TM1 Queries and Aliases......................................................................................................... 15
35. Data Source Connectivity Requirements for the Application Server: ..................................... 19
36. Using an External Microsoft Excel File Source located on a network drive on User Machine 19
Report Generation/Validation .................................................................................................................... 20
37. Validation Report .................................................................................................................... 20
38. Generate Microsoft Word Document with Microsoft Excel Range Variable .......................... 20
Roll forward/Cascade Report ...................................................................................................................... 21
39. Query Variables and Roll Forward Operation ......................................................................... 21
Miscellaneous ............................................................................................................................................. 21
40. Custom Groups and New Objects ........................................................................................... 21
41. Reference Variables and Shared Objects ................................................................................ 21
42. Variable naming convention ................................................................................................... 21
Appendices.................................................................................................................................................. 23
1. CDM Deployment on Multiple Environments............................................................................. 23
2. Restoring CDM database if it originated from a different application server ............................ 26
3. Encrypting/Decrypting ConnectionString.config ........................................................................ 28
3|Page
Architecture/Installation:
1. Click Once Deployment.
Description: When installing Cognos Disclosure Management with Click-Once Deployment, the
installation process may be interrupted/encounter issues if all the required prerequisites are not
installed on the client-machine. The same applies if the user does not have read/write access to
the AppData folder (Example: C:\Users\Administrator\AppData)
Best Practice: Ensure that correct prerequisites are installed including the Microsoft Visual C++
2010 x86/x64 Redistributable packages. For a full list, please refer to product documentation.
Read/Write access to the AppData folder is also required prior to deployment, if using the Click-
Once installation process.
2. Application Server Deployment.
Description: Users may encounter a connection issue while logging into the application after a
fresh installation of the Cognos Disclosure Management Application Server. This applies in a
scenario where the SQL Server is on a different machine than the Application Server.
Best Practice: While deploying CDM, the installation process sets the Application Pool Identity
used by the Application Server to Local System. This should then be changed using the following
steps:
a. On the Application Server, open Internet Information Services Manager

b. Navigate to Application Pools, and right-click on CognosDMServerApplicationPool and
click Advanced Settings.
c. Once that is open, click on Identity ellipsis under Process Model. Once open, select
Custom Account. The credentials that are required here are that of an administrator
user on the Application Server.
4|Page
d. Furthermore, the data encryption key may not have been installed on the database due
to the fact that the CDM Application Server installer does not pass through Windows
credentials from the installation wizard to the database server it is being deployed to.
This is why it is necessary to perform this next step if the Application Server and the
Database reside on another machine.
e. In order to create the encryption used by the application server, the following must be
must be performed:
Open command prompt console, change directory to C:\inetpub\wwwroot\CognosDM-

Server\Tools\EncryptionTool and run the following command:
SetMasterAndEncryptionKeys.bat [SQLSERVER\INSTANCE] database 'masterkey'

C:\inetpub\wwwroot\CognosDM-Server\web.config
Ibm.CognosDM.DatabaseEncrypter.dll
Note:'masterkey' is a placeholder for a password used in the encryption process.
Example: SetMasterAndEncryptionKeys.bat [dbserver.domain.com\Prod] CDM

'masterkey' C:\inetpub\wwwroot\CognosDM-Server\web.config
Ibm.CognosDM.DatabaseEncrypter.dll
Note: Ensure that the user performing this operation has sysadmin rights to the database using
their Windows credentials as opposed to using SQL Authentication.
3. CDM Deployment on Multiple Environments
Description: When deploying CDM for the first time, it is important to plan out the number of
required environments prior to performing the installation process. This is due to the fact that
CDM application can only be installed once per application server.
Best Practice: CDM will need to be configured separately if multiple environments are required
such as Production/UAT. Note that since database encryption is applied at installation time, the
databases installed on the different servers can only be accessed using its appropriate web
service.
Example: Suppose you have a Prod and a UAT environment. You cannot trigger the UAT Web
Service to connect to the Prod database when there is already a UAT database associated with
the service. This is because encryption between the Web Service and database is applied. The
best practice here is to restore the Prod database into UAT environment and apply appropriate
encryption command to sync the new database with the Prod Web Service. This process is
outlined in detail in another document. See Appendix 1 for more details.
5|Page
4. CDM Client Deployment
Description: While logging into CDM after client installation of client, you may encounter the
following error:
Best Practice: Install the CDM Client by a user with Administrative rights. Also ensure that the
user logging in has read/write access to that file location as logs might be generated in the same
folder.
6|Page
Security:
5. Workflow Object Security
Description: CDM is a permission-driven application that allows users to create reports that may
be accessible across other teams. In this case relevant permissions at report level should be
granted to those individuals who intend to view or contribute to the report content.
Best Practice: If there is any sensitive information that cannot be shared across multiple groups,
ensure to create User Groups and assign appropriate View Report permissions to control user
access to those reports
6. Change Reference and Object Security
Description: If there are references to objects in the report pointing to an original shared object,
Change Reference feature allows the user to modify the reference to point to another source
shared object. This may expose object content to other financial groups as shown in the Use
Case below:
Master Report Cascade Report

Cascade
(2011) (2011)
Roll Forward Roll Forward
Master Report Cascade Report

(2012) (2012)
As a user, I am able to Change Reference of Cascade Report (2012) to point to reference

objects in Master Report (2012) since they are in the same Cascade Chain.
Best Practice: If there is any sensitive information that cannot be shared across multiple groups,
ensure to create User Groups and assign appropriate Change Reference/View Report
permissions to control user access to those reports from different entities.
7. Password Complexity
Best Practice: When creating users in CDM, passwords must align with Microsoft recommended
password complexity:
 The password does not contain all or part of the account name of the user. Part of an
account name is defined as three or more consecutive alphanumeric characters
delimited on both ends by white space such as space, tab, and return, or any of the
7|Page
following characters: comma (,), period (.), hyphen (-), underscore (_), or number sign
(#).
 The password is at least eight characters long.
The password must contain characters from three of the following four categories:
- Latin uppercase letters (A through Z)
- Latin lowercase letters (a through z)
- Base 10 digits (0 through 9)
- Non-alphanumeric characters such as: exclamation point (!), dollar sign ($), number
sign (#), or percent (%).
8. Automatic Login
Best Practice: When logging into CDM using Active Directory/CAM authentication without
retyping credentials, enable the Remember Me option prior to authenticating. You will still need
to enter Username and Password information but once this is selected, it will store all preferred
settings in a file in the User’s home folder. See below example:
Alternatively, the user may manage the list of servers, as well as specify the default one, in the
CDM option screen (File->Options):
9. Importing Groups from AD with Auto-Registrable option
Description: The following steps describe the Import Group from AD/CAM Logic:
1. User with appropriate rights to query Active Directory/Cognos Access Manager sources
should be used to import group to CDM. (The users in the group must be members of the group
in AD/CAM in order for the Auto-Registerable feature to work)
8|Page
2. Mark group as Auto-Registerable in CDM after import
Conclusion: Each user who is a member of the imported group will be automatically imported
into CDM at first login. Please note importing groups within CDM only brings in a flat list of the
selected group(s) and does not bring in the relationship of Groups and Users.
Best Practice: It is best practice to assign permissions to the group so that you don’t have to
assign permission per user. If a new user is added to Active Directory/Cognos Access Manager
(CAM) and that user is part of the imported group, that new user can be registered to the Users
list automatically.
Workflow:
10. Bulk Workflow Operation
Description: When working with multiple objects, users are able to perform bulk workflow
edits/creation that may expose them to performance restriction from the CDM Client-side.
Best Practice: Bulk Workflow Edit/Update operations should be limited to ~ 50-60 objects for a
single operation. It is recommended to perform bulk operation on as few objects (single digits)
as possible.
11. Template Workflow Design
Description: If a template workflow is applied in an object, modifications made to the template

in Application level will not directly update the objects that have applied it previously since they
are brought as a copy. Alternatively, you may use referenced template workflows which update
the workflow dynamically, if it changes at Application Level.
Best Practice: Ensure templates created fit the business requirement in case of mistakes
resulting in re-applying workflow to many objects.
Report and Object Management:
12. Importing Objects
Description: CDM allows the user to import large number of objects in the report object tree
structure. If multiple objects are selected to be imported at once, the operation may take some
time to complete due to the size of the request and server/client communication speed.
9|Page
Best Practice: Import objects based on smaller bulk chunks to avoid any unnecessary
performance drawbacks as a result of the bulk operation.
In addition, the cumulative size of selected objects should not exceed the following when
performing a single bulk import operation:
 When importing 1-2 objects, original file should not exceed 50MB
 When importing <=5 objects, original file should not exceed ~ 5-50MB
 When importing <= 25 objects, original file should not exceed ~1-5MB,
 When importing <= 40 objects, original file should not exceed ~100K-1MB
13. Deleting Bulk Objects
Description: CDM allows the user to also delete large number of objects in the report object
tree structure. If multiple objects are selected to be deleted at once the operation may take
some time to complete due to the size of the request and server/client communication speed.
Best Practice: Delete objects based on smaller bulk chunks. It is always preferred to delete a
single object at a time so that the user can be sure of not deleting a required object.
14. Object Hierarchy and Delete Behaviour
Description: The object tree view in CDM allows for different combinations of objects and blank
sections that allow users to break down the object structure in a hierarchical format. When
deleting a parent object, all child objects will be deleted. This is similar behaviour to Windows
when it comes to folder/file structure. Take into consideration that this also applies when
selecting multiple objects while one object selected is a parent object. The user will be notified
when deleting an object so they are aware of the deletion process.
Best Practice: If any time a parent object needs to be deleted without its child object(s), simply
drag/drop the child object(s) outside of the parent/child hierarchy. Once finished, you will
notice that the parent object will no longer have a hierarchy and is now safe to delete.
15. PDF Objects
Description: When creating a PDF object, an issue may be encountered where the PDF that is
imported will not be viewable in CDM. This may cause the object to become unresponsive and
could result in errors.
Best Practice: Adobe Acrobat must be configured to disable Protected View on Startup. This can
be found under the General options.
10 | P a g e
16. Microsoft PowerPoint Objects
Description: Microsoft PowerPoint objects can be used to retrieve variable values, Microsoft
Excel Charts, Microsoft Excel Named Ranges and Image Variables at generation time. When
generating an Microsoft Excel Named Range to Microsoft PowerPoint, the following Microsoft
Excel properties will not be preserved:
o Shrink to fit cell property as there is no equivalent property in Microsoft PowerPoint.
o Microsoft Excel Cell truncation: If a piece of text is being cut-off due to the size of the
cell, the cut-off text will not appear for the same reason as above.
Best Practice: Prior to generating the object to Microsoft PowerPoint, ensure that the cells with
the problematic text are displayed properly in the Microsoft Excel cell without truncation of
original content. An alternative method to this is to use Image Range Variables to display the
content of the range in the form of an Image.
11 | P a g e
Background: Microsoft PowerPoint Microsoft Excel however, does have this

table cells do not have the capability for capability and it can be seen under the
the auto-fit feature for Shapes. See cell property:
below screenshot:
The main reason it is grayed-out in Microsoft PowerPoint is because a table is considered as a

shape. Shape controls do not have the option. This is proven if you insert a Microsoft
PowerPoint textbox: the auto-fit section will then be enabled.
CDM converts Microsoft Excel tables to Microsoft PowerPoint tables, hence, this Microsoft
design limitation must be considered when working with Microsoft Excel/Microsoft PowerPoint
Objects.
In addition, Microsoft PowerPoint tables have a small padding that does not appear in Microsoft
Excel cells. See below:
This may also impact the generated document in that sense since there is no method to control
this mechanism.
12 | P a g e
17. Microsoft Excel Objects: External Links
Description: Data may not be refreshed properly if an Microsoft Excel object is referencing data
from an Microsoft Excel file using External Links as this scenario is not supported.
Best Practice: The best practice to avoid this scenario would be to create an External Microsoft
Excel File Source/Query and inserting this into the Microsoft Excel object. Data at that point will
be refreshed automatically or manually by the user to ensure that it is consistently updated,
unless the object is locked.
18. Microsoft Excel Objects: Reserved Ranges
Description: Refresh issues may arise if Microsoft Excel reserved range names are used when
creating a range variables in CDM.
Best Practice: Microsoft Excel uses reserved range names for some of its own features. For this
reason, you should not use any of these range names:
- Consolidate_Area
- Print_Titles
- Auto_Open
- Recorder
- Auto_Close
- Data_Form
- Extract
- Auto_Activate
- Database
- Auto_Deactivate
- Criteria
- Sheet_Title
- Print_Area
13 | P a g e
Alternatively, you may use the Microsoft Word Var in-front of the range names that uses this
string
Example: Var_Consolidate_Area
19. Microsoft Excel Objects: Add-in Mode
Description: When working in Add-in mode, an extra process will be created in the Windows
Taskbar when using Office 2003. This is currently how Microsoft Excel works with Windows 7.
This does not occur for Office 2007/2010.
20. Microsoft Excel Objects: Using Now(), Workday () formulas in Microsoft Excel calculations
Description: If there are any Microsoft Excel formulas returning results based on Now() and
Workday() functions, the time/workday formula will return the result based on the last saved
time of the object, not the date/time the object is opened.
Best Practice: The user must unselect Cached Data when generating in order to see the correct
date and time. In order to still use Cached data in this scenario, variables may be used to force
refresh of objects with Now(), Workday().
21. Microsoft Excel Objects: Image Range Variables (##IRS/##IRE)
Description: When generating an Microsoft Excel Image Range using ##IRS/##IRE derivative, the
final output of the image may not be the same size as how it is defined in the Microsoft Excel
Object.
Best Practice: When defining the hyperlink for the image range in the Microsoft Word object,
you must:
1. Insert a 1x1 table and resize it to the appropriate size required.
2. Ensure that the resize parameter is used when creating the hyperlink.
Example: cdm:CustomRange:objectName:sheetName?snapshot &resize.
22. Resolving Microsoft Excel Range Variables in Microsoft Word Objects
Description: If a Microsoft Word object is retrieving a ##D/##GD range variable from an

Microsoft Excel object, any variables that are defined in that range will not be resolved. In
addition, the range variable will generate based on how it is defined in the Microsoft Excel
object without post-processing calculation of:
-Automatic Row/Column Suppression
-Superscripts
-Microsoft Excel Page Breaks
-Padding
8|Page
Best Practice: If a note variable is required in the destination Microsoft Word object, enter the
note variable directly in the object, as opposed to in the range variable. Using this method
allows for both the range variable content, as well as the note variable, to resolve after the
object is generated.
9|Page
23. Page Setup and Office Theme Fonts
Description: Page setup objects require dummy text to be able to enforce Font Type, Font Size,
and Paragraph/Table keep with Next attribute. When defining this text, the user may run into a
situation where they select Office Theme Fonts (a font specific to an Office theme such as
“Header” or “Body”). If an Office Theme Font is used instead of a normal font, this font will not
be enforced and will default to Times New Roman. See below example of Office Theme Fonts:
Office 2007 Office 2010
Best Practice: Ensure that the font type used for the dummy text is simply any font that is not a
theme font as shown below
Office 2007 Office 2010
24. Object Properties: Break Type
Best Practice: The following should be considered when setting up the break type for an object
to New Page:
 # of Page set to 0: The content of the object will just be pushed to following page, no
new pages are inserted.
 # of Page set to 1: One full page will be inserted between the current and the preceding
object and the content of the object will be pushed down to the following page.
25. Variable Chaining
Description: Variable Chaining occurs when two references variables (##S/##D) are used in
conjunction at any certain point in an Microsoft Excel object. See below example:
10 | P a g e
Here we have a variable defined as “test1”. Chaining in this example occurs when variable
“test2” references the result of “test1”. The value for “test2” is depended on the output of
“test1”. This is known as multi-level variable reference. CDM only supports one-level references
of (##S/##D, ##GSD/##GD).
The above example is quite a simple one but in most scenarios, the user may chain variables
throughout multiple references of Microsoft Excel cells. See below:
Here, we have cell E11 adding all the cells from E5 to E10 as well as M6. At the same time, the
“test2” variable references E11. This is type of behaviour is also considered variable chaining
because we’re including a ##S and ##D in the same instance (through different cell references).
Symptoms of Variable Chaining
 Certain Microsoft Excel cells do not refresh accordingly. This doesn’t have to happen to the
whole document but can happen to only a few cells. To see if the object is affected by this
behaviour, you could navigate to the object where the source variable resides, refresh the
object and then navigate back into the object where the variables are not refreshing. The
“old” value at this point will be updated to the new value.
 Another symptom for variable chaining is that the refresh issue is intermittent. It may/may
not happen.
11 | P a g e
Best Practice: It is recommended best practice to design all Microsoft Excel objects in a way
where any number being referenced in a formula or to another cell, is not linking to a
destination variable (##D/##GD). This is prevalent in Microsoft Excel objects with range
variables. A user may define a range variable in an object and another user may reference a cell
in that object, which happens to be in that range. As a result, if information changes in the
source range variable, these changes aren’t updated in the destination variable, causing the user
to see old numbers.
26. Working with Microsoft Excel objects and HFM SmartView formulas
Description: CDM supports the following HFM SmartView custom formulas:

 HsGetValue
 HsGetText
 HsLabel
 HsCurrency
 HsDescription
Best Practice: In order to refresh HFM formulas using the Smart View add-in while in an
Microsoft Excel object, Add-in Mode must be enabled from the Report Object ribbon menu. This
allows for CDM to communicate with the HFM add-in refresh process to update the values of
the formulas from the source.
27. Automatic Refresh of HFM SmartView formulas
Description: Since the application server does not communicate with the HFM Add-in installed
on the user’s local machine, it is important to add the HFM source in Data Source Management.
This allows for automatic refresh of formulas during report generation.
Best Practice: In order to ensure that HFM formulas are refreshed in all report objects
dynamically, the HFM source must be associated in the objects that use HFM formulas. This can
be achieved by clicking on Manage HFM Server in the Microsoft Excel Data Ribbon.
Furthermore, ensure that the connection name specified in the HFM Formula have the same
name as the HFM data source defined in Data Souce Management. This action will create a
12 | P a g e
pointer from the CDM Web Service and the HFM Source to refresh HFM formulas when
generating a report.
In addition, you may associate multiple HFM data sources in one object if the formula is coming
from two different sources.
Data Source/Query Management:
28. TM1 Data Source vs. TM1 Perspective in CDM
Description: CDM provides Cognos TM1 integration in two ways:

1. Creating an OLAP TM1 Source/Query as External Data that can be inserted many times
in different Microsoft Excel objects. Also, by using this method, data is retrieved from
the Cache database; hence it is better in terms of performance.
2. Using TM1 Perspectives Microsoft Excel-Add-in
Both methods allows for data retrieval from a TM1 cube. The caveat here is that the first
method allows for dynamic data refresh upon opening/saving objects and when generating a
report. The second method relies on the user to refresh data/formulas on demand from the
cube using the TM1 Perspectives Microsoft Excel Add-in. This also has an impact on locking
functionality where locking does not control the data retrieved if the user were to manually
update data.
Best Practice: It is recommended that the first method is used in order to ensure that all TM1
queries are created in a structured format while leveraging dynamic refresh/locking capability of
the application. First method is also better from performance and scalability standpoint. For
example, user can create a TM1 Query just once and share the query with one or multiple
reports without having to recreate it. Also, by performing an update to this query in one place
will propagate the changes to all of its references across reports.
29. Cognos Controller in CDM
Description: In order to leverage Cognos Controller in CDM using Data Source/Query

Management, the Controller database must be converted to a TM1 cube using Cognos Financial
Analytics Publisher tools. Once converted, Controller data can be queried using the same
method for TM1.
Alternatively, Cognos Controller Microsoft Excel Add-in may be used in an Microsoft Excel object
but this method will not provide dynamic refresh through the application. The user will have to
refresh each object using the Microsoft Excel Add-in should they require the
information/formulas to update.
13 | P a g e
Best Practice: It is recommended that the first method, as defined as part of the “TM1 Data
Source vs. TM1 Perspective in CDM“ best practice, is used in order to leverage dynamic
refresh/locking capability of the application when working with Cognos Controller data.
30. Cognos For Microsoft Office/Cognos Analysis for Microsoft Excel in CDM
Description: CDM also provides integration with Cognos for Microsoft Office or Cognos Analysis
for Microsoft Excel using IBM Cognos for Microsoft Office Microsoft Excel Add-in where both
functionalities may be used.
Best Practice: The following considerations should be taken when working with Cognos for
Microsoft Office/ Cognos Analysis for Microsoft Excel Microsoft Excel Add-in:
- The same version of Cognos for Microsoft Office/Cognos Analysis for Microsoft Excel
needs to be installed. This requirement applies outside CDM.
- To use Cognos for Microsoft Office /Cognos Analysis for Microsoft Excel functionality,
the Microsoft Excel object must first be checked-out by the current user. That way,
information can be saved accordingly without any potential data loss.
31. Cognos For Microsoft Office Search functionality and Office 2003
Description: When using the Cognos for Microsoft Office search functionality with Office 2003,
the search window may not focus on the form properly. Closing and opening the search window
may also present the same problem.
Best Practice: This issue is only present using the Cognos for Microsoft Office add-in for Office
2003. If search functionality is required, Office 2007/2010 may be used.
32. Cognos For Microsoft Office behaviour with multiple Microsoft PowerPoint Instances
Description: Cognos For Microsoft Office may encounter issues retrieving reports when multiple
instances of Microsoft PowerPoint Objects are open in CDM. This only occurs if a Microsoft
PowerPoint object is already open with the For Microsoft Office add-in while attempting to use
the add-in in the second instance.
Best Practice: It is recommended that when working with Microsoft PowerPoint objects, only to
use Cognos for Microsoft Office in one Microsoft PowerPoint instance. Multiple instances may
be used with Microsoft Excel/Word objects.
14 | P a g e
33. Editing External Microsoft Excel File Structure
Description: Special considerations must be taken when adding/removing rows and columns in
an External Microsoft Excel File that is being linked to a Data Query in an Microsoft Excel object.
Retrieving data from the Datasheet (Database/Custom) to the active sheet utilizes direct cell
references in the object. This means that if the structure of the data in the External Microsoft
Excel file changed, any cell references in the active sheet may incorrectly point to different cells.
Best Practice: Prior to loading the data in the Microsoft Excel Object, it is important to finalize
the structure of the External Microsoft Excel file that will be leveraged via the Microsoft Excel
Query to make sure that no rows/columns will need to be modified after inserting the queries.
That way, you only need to refresh the data from the source should numbers/text get updated.
If a change in structure is necessary having inserted the Microsoft Excel query, it is best practice
to review and update the direct cell references that are affected by this change to ensure that
data is pointing to the correct values.
34. TM1 Queries and Aliases
Description: IBM Cognos TM1 cubes allow the user to define multiple aliases when working with
dimensions and dimension members. For that reason, if multiple aliases are defined in a TM1
Cube, the “Show Alias” option may not trigger the correct alias information required when
working with a TM1 Query.
Best Practice: To leverage the “Show Alias” option if more than alias is defined in a TM1 cube, a
preferred Alias with a name of “MEMBER_CAPTION” must be defined for that dimension
required. You must ensure that all of the dimension members correspond to an alias name.
1. After logging into the cube in TM1 Architect, select the dimension that contains multiple
aliases:
2. Right click on the dimension and click Edit Element Attributes
15 | P a g e
3. This will bring up the dimension explorer where you may edit all attributes of the selected
dimension. You will notice the multiple dimensions in the cube.
4. Right click on any of the columns in the above screen and select Add new Attribute
5. Type in MEMBER_CAPTION in the name field. Be sure to select Alias for attribute type.
16 | P a g e
6. You will notice the newly created attribute in the explorer and will have the default name
automatically mapped.
This can be customized to meet the required name of the member in the dimension by simply
selecting the field and typing in a new name:
17 | P a g e
Alternatively, you may copy/paste a name from another attribute if required by simply right
clicking on the field and selecting Copy. Once done these Aliases will be available within CDM
TM1 wizard.
18 | P a g e
35. Data Source Connectivity Requirements for the Application Server:
Description: Creating a data source requires the user to install the appropriate Runtime client
for the data source:
 If you have installed TM1 Perspectives, you will require the TM1 Runtime client 64-bit,
Version 10.1
 Microsoft Analysis Services ADOMD.NET 2005 or 2008
If you use Oracle Essbase software, connectivity and installation of the correct Oracle Essbase
Runtime client software is required:
 Oracle Instant Client

 Oracle Data Provider for .NET
The DB2 relational source requires installation of the DB2 ADO.NET client Runtime component
36. Using an External Microsoft Excel File Source located on a network drive on User Machine
Description: Due to security reasons with network drives, the CDM Web Service must be
explicitly configured to define an account (User Name and Password) to leverage when querying
an External Microsoft Excel file residing on a network drive.
Best Practice: Edit the CDM.config configuration file located in the Web Service folder. Navigate
to Data Source Credentials and input the Username and Password as shown below:
At this point, this account will be used for any External Microsoft Excel File Data Source that
resides on a network drive. Please ensure that the account specified has necessary read/write
access to the network drive location. It is best practice to leverage one account for this that has
this type of access across multiple drives.
Note: The password for this type of account currently is not encrypted as it is an additional
configuration being made after the installation process. Since the CDM Web Service will be
deployed in a secure environment, it is recommended to only have a few users with read access
this file.
19 | P a g e
Report Generation/Validation
37. Validation Report
Description: Report validation using ##R variables, is conducted automatically when generating
a report or manually using the Validate Report button. Manual Report Validation does not
automatically refresh the cached data hence, some validation rules may fail if source
information was changed while the Cache database contains non-synced data.
Best Practice: It is recommended to refresh the report using Refresh Report button prior to
executing manual report validation. This ensures that all the data connected to variables, data
sources and reference objects are updated so that the rules can apply with its correct value.
38. Generate Microsoft Word Document with Microsoft Excel Range Variable
Description: When generating a Microsoft Word document that is retrieving an Microsoft Excel
Range variable (using ##D/##GD), hidden rows/columns in the Microsoft Excel Range will not be
preserved when it is generated in the Microsoft Word document.
Best Practice: It is recommended practice that when defining the Microsoft Excel range to be
used in a Microsoft Word document, not to have any hidden columns/rows. If they are
necessary, then the Microsoft Excel object containing the hidden rows/columns can be
generated directly, without relying on a range variable.
20 | P a g e
Roll forward/Cascade Report
39. Query Variables and Roll Forward Operation
Best Practice: When rolling forward a report that contains query variables at report and object
levels, prior to executing the roll forward process, the query variables must be overridden with
the option “Visible on Rollover”. Without this option selected, the new report will inherit values
from application-level as opposed to the overridden values at report and object levels.
Miscellaneous
40. Custom Groups and New Objects
Description: A CDM report may be opened via a custom group which is merely a filter to show
relevant objects for a certain reporting period. It is important to note that newly created objects
will not be associated to that to the custom group the report is opened with. This means that if
the report is opened by a different user, it will not display that object.
Best Practice: When required, new objects can be associated to the custom group using the
report object tree context menu under Properties:
41. Reference Variables and Shared Objects
Description: It is important to note that ##D/##GD variables will always resolve to the local
report, hence, this should be considered during initial design.
Best Practice: ##S variables should not be declared in a shared object as it may conflict with
other variables with the same name across different reports. If ##D variables are in the object,
relative #S variable must also be defined in the destination reports.
42. Variable naming convention
Best Practice: From consistency stand point it is recommended to follow a specific syntax when
naming variables within the application. For example,
21 | P a g e
 All variables start with 3 letters prefix – var, followed by 3 letter Microsoft Word that
defines the variable e.g. varAssets, varLiabilities
 Follows Camel Casing. E.g. if you have more than one Microsoft Word that makes up a
variable then the variable name could follow syntax: varCurAssets, varCshFlow. These
variables would stand for Variable Current Assets and Variable Cash Flow.
22 | P a g e
Appendices
1. CDM Deployment on Multiple Environments
Description: The CDM Application Server installer will not deploy the CDM Web Service that has
already been deployed previously. A manual process is required to add multiple web services on
one Application Server. This is achieved by using the following steps;:
1. After successful installation, the CDM Web Services will be deployed on the directory
specified in the installer. Copy and Paste the same directory deployed to the desired location.
2. Backup the Prod database from SQL server and Restore the same database into the desired
environment.
Important: If the CDM Application Server installation was performed on a different physical
machine than the one the database was restored to, it is important to refer to additional
documentation below to ensure that
3. Edit the ConnectionString file in the newly pasted folder to point to the required database as
shown below:
Note: If the SQL user credentials are specified, they may be encrypted. Ensure to use the CDM
Encryption utility to encrypt/decrypt prior to executing this step. After editing the database and
credentials, be sure to encrypt the username and password in this file.
4. Convert the pasted web service folder into an ASP application using IIS Manager as shown
below:
23 | P a g e
24 | P a g e
Note: Ensure to select the appropriate Application Pool similar to the previously deployed
installation. In this example, it will be CognosDMServerApplicationPool. Alternatively, you may
create a separate application pool using the following Application Pool settings:
5. Ensure that Anonymous authentication is enabled in IIS Manager if it is not already enabled.
See screenshot below:
25 | P a g e
2. Restoring CDM database if it originated from a different application server
Background: A master key is created during installation and is compiled based off a key phrase
combined with machine information. This is to prevent unauthorized users from restoring and
connecting to the database via the client.
Each time the CDM Server is installed, it will encrypt the database using this masterkey. It is a
necessary step to Export/Import the Masterkey file as part of the process of moving a database
from one environment to another.
1. Export master key from the source application server using the Encryption Tool. This step will
have to be performed by the client. Once the key is exported, it will be sent to us in order to
apply their own key and use the database in our environments.
CDM comes with an Encryption Utility that allows users to create/encrypt/export master key
files. Open up command prompt (Ensure to run as Administrator). Navigate to the Tools folder
in the website root.
For example: cd c:\inetpub\wwwroot\CognosDM-Server\Tools
Once there, we will need to execute the following command:
Ibm.CognosDM.EncryptionTool.exe /EMK /cfgfile:" path\to\Web.config "

/o:"path\to\output\location"
Note: You only need to modify the location of the web.config file as well as the output location
in this command. Replace the path for /cfgfile with actual location of your web.config file. The
/o parameter specifies the output location. Replace the content after that to the location
desired to export the key.
For Example:
Ibm.CognosDM.EncryptionTool.exe /EMK /cfgfile:"C:\inetpub\wwwroot\CognosDM-
Server\Web.config" /o:"C:\Websites\Backup"
Once finished, press Enter. You should get a DONE message displayed in the command prompt.
If there are any errors, it will most likely be regarding syntax.
2. Back up the MasterKey.txt file from the destination server. This will be your own masterkey
you have set up. That way, any issues encountered we can still restore the original.
3. Back up the database at the source server.
4. Restore the database at the destination server.
5. Modify the Connection String file at the destination server to point to the newly restored
databases. Ensure both regular and Cache database are restored.
26 | P a g e
ConnectionString can be found under the Config folder in your root webservice location. For
Example: C:\inetpub\wwwroot\CognosDM-Server\Config
Below screenshot shows what needs to be modified:
6. This is the final step. We will need to restore the master key exported from the source server
into the destination server. This will require command prompt as well so ensure you run
command prompt as an Administrator.
Once open, navigate to the same directory as in Step 1.
For example: cd c:\inetpub\wwwroot\CognosDM-Server\Tools
Once there, we will need to execute the following command:
Ibm.CognosDM.EncryptionTool.exe /SMK /newkey:"path/to/exported/masterkey"

/keyformat:file /cfgfile:"path\to\Web.config"
Note: We will need to replace the “path/to/exported/masterkey” with the actual location of the
exported key from Step 1. Content in quotations after cfgfile need to be replaced with the
location of the web.config file.
For Example:
Ibm.CognosDM.EncryptionTool.exe /SMK /newkey:"C:\Websites\Backup\key.txt"
/keyformat:file /cfgfile:"C:\inetpub\wwwroot\CognosDM-Server\Web.config"
Once finished, press Enter. You will have received a similar message “DONE” to indicate the
process is complete. Any errors that may appear will be due to syntax issue.
After the command is executed, and is successful, you are now able to log into CDM using the
newly restored database!
27 | P a g e
3. Encrypting/Decrypting ConnectionString.config
Description: Use the ConfigFileEncryptionTool.bat file to encrypt the configuration file to

protect the connection strings in CDM. The installer automatically calls the
ConfigFileEncryptionTool.bat file to encrypt connection strings.
Best Practice: If you want to change a connection string to specify a different server for the
database, use the ConfigFileEncryptionTool.bat file to decrypt the file, edit it, and then encrypt
it.
To decrypt the connections strings, run the following command:
ConfigFileEncryptionTool.bat decrypt c:\ path_to_folder_containing_web.config
Example: ConfigFileEncryptionTool.bat decrypt c:\Inetpub\wwwroot\CognosDM-Server
To encrypt the connection strings, run the following command:
ConfigFileEncryptionTool.bat encrypt c:\ path_to_folder_containing_web.config
Example: ConfigFileEncryptionTool.bat encrypt c:\Inetpub\wwwroot\CognosDM-Server
Important: Do not include a backslash at the end of the path to the web.config file.
28 | P a g e

CDM Best Practice

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

CDM Best Practice

Uploaded by

Copyright:

Available Formats

IBM COGNOS DISCLOSURE

MANAGEMENT 10.2 – BEST Best Practices ver.

PRACTICES DOCUMENT VER. 1.0

This document is designed to provide insights to some commonly used best

2. Application Server Deployment.

a. On the Application Server, open Internet Information Services Manager

Open command prompt console, change directory to C:\inetpub\wwwroot\CognosDM-

SetMasterAndEncryptionKeys.bat [SQLSERVER\INSTANCE] database 'masterkey'

Note:'masterkey' is a placeholder for a password used in the encryption process.

Example: SetMasterAndEncryptionKeys.bat [dbserver.domain.com\Prod] CDM

3. CDM Deployment on Multiple Environments

4. CDM Client Deployment

6. Change Reference and Object Security

Master Report Cascade Report

Roll Forward Roll Forward

Master Report Cascade Report

As a user, I am able to Change Reference of Cascade Report (2012) to point to reference

9. Importing Groups from AD with Auto-Registrable option

2. Mark group as Auto-Registerable in CDM after import

11. Template Workflow Design

Description: If a template workflow is applied in an object, modifications made to the template

Report and Object Management:

12. Importing Objects

13. Deleting Bulk Objects

14. Object Hierarchy and Delete Behaviour

15. PDF Objects

16. Microsoft PowerPoint Objects

Background: Microsoft PowerPoint Microsoft Excel however, does have this

The main reason it is grayed-out in Microsoft PowerPoint is because a table is considered as a

17. Microsoft Excel Objects: External Links

18. Microsoft Excel Objects: Reserved Ranges

19. Microsoft Excel Objects: Add-in Mode

21. Microsoft Excel Objects: Image Range Variables (##IRS/##IRE)

22. Resolving Microsoft Excel Range Variables in Microsoft Word Objects

Description: If a Microsoft Word object is retrieving a ##D/##GD range variable from an

23. Page Setup and Office Theme Fonts

Office 2007 Office 2010

24. Object Properties: Break Type

25. Variable Chaining

Symptoms of Variable Chaining

Description: CDM supports the following HFM SmartView custom formulas:

27. Automatic Refresh of HFM SmartView formulas

Data Source/Query Management:

28. TM1 Data Source vs. TM1 Perspective in CDM

Description: CDM provides Cognos TM1 integration in two ways:

29. Cognos Controller in CDM

Description: In order to leverage Cognos Controller in CDM using Data Source/Query

33. Editing External Microsoft Excel File Structure

34. TM1 Queries and Aliases

2. Right click on the dimension and click Edit Element Attributes

35. Data Source Connectivity Requirements for the Application Server:

 Oracle Instant Client

37. Validation Report

Roll forward/Cascade Report

39. Query Variables and Roll Forward Operation

40. Custom Groups and New Objects

41. Reference Variables and Shared Objects

42. Variable naming convention

1. CDM Deployment on Multiple Environments

2. Restoring CDM database if it originated from a different application server

For example: cd c:\inetpub\wwwroot\CognosDM-Server\Tools

Once there, we will need to execute the following command:

Ibm.CognosDM.EncryptionTool.exe /EMK /cfgfile:" path\to\Web.config "

3. Back up the database at the source server.