Cognos Disclosure Management 10 2 Best Practice Document Jan 08 2013 PDF

IBM COGNOS DISCLOSURE
MANAGEMENT 10.2 BEST Best Practices ver.

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

practices as applied to IBM Cognos Disclosure Management version 10.2.0
IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.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
5. Application Pool and Idle Time-out .............................................................................................. 7
Security: ........................................................................................................................................................ 9
6. Workflow Object Security ............................................................................................................. 9
7. Change Reference and Object Security ........................................................................................ 9
8. Password Complexity .................................................................................................................... 9
9. Automatic Login .......................................................................................................................... 10
10. Importing Groups from AD with Auto-Registrable option ...................................................... 10
Workflow: ................................................................................................................................................... 11
11. Bulk Workflow Operation ....................................................................................................... 11
12. Template Workflow Design..................................................................................................... 11
Report and Object Management: ............................................................................................................... 11
13. Importing Objects ................................................................................................................... 11
14. Deleting Bulk Objects .............................................................................................................. 12
15. Object Hierarchy and Delete Behaviour ................................................................................. 12
16. PDF Objects ............................................................................................................................. 12
17. Microsoft PowerPoint Objects ................................................................................................ 13
18. Microsoft Excel Objects & Alignment Enforcment Setting ..................................................... 15
19. Microsoft Excel Objects: External Links .................................................................................. 16
20. Microsoft Excel Objects: Padding Value ................................................................................. 16
21. Microsoft Excel Objects: Custom Margins and Excel Tables ................................................... 17
22. Microsoft Excel Objects: Reserved Ranges ............................................................................. 24
23. Microsoft Excel Objects: Add-in Mode ................................................................................... 24
24. Microsoft Excel Objects: Using Now(), Workday () formulas in Microsoft Excel calculations 24
25. Microsoft Excel Objects: Image Range Variables (##IRS/##IRE) ............................................. 25
26. Hyperlinks in CDM ................................................................................................................... 25
2|Page
27. Resolving Microsoft Excel Range Variables in Microsoft Word Objects ................................. 29
28. Page Setup and Office Theme Fonts ....................................................................................... 30
29. Object Properties: Break Type ................................................................................................ 30
30. Variable Chaining .................................................................................................................... 30
31. Working with Microsoft Excel objects and HFM SmartView formulas ................................... 32
32. Automatic Refresh of HFM SmartView formulas .................................................................... 32
Data Source/Query Management:.............................................................................................................. 33
33. TM1 Data Source vs. TM1 Perspective in CDM ....................................................................... 33
34. Cognos Controller in CDM....................................................................................................... 33
35. Cognos For Microsoft Office/Cognos Analysis for Microsoft Excel in CDM ............................ 34
36. Cognos For Microsoft Office Search functionality and Office 2003 ........................................ 34
37. Cognos For Microsoft Office behaviour with multiple Microsoft PowerPoint Instances ....... 34
38. Editing External Microsoft Excel File Structure ....................................................................... 35
39. TM1 Queries and Aliases......................................................................................................... 35
40. Data Source Connectivity Requirements for the Application Server: ..................................... 39
41. Using an External Microsoft Excel File Source located on a network drive on User Machine 39
42. Configuring Excel Data Query Row Limit ................................................................................ 40
Report Generation/Validation .................................................................................................................... 41
43. Validation Report .................................................................................................................... 41
44. Generate Microsoft Word Document with Microsoft Excel Range Variable .......................... 41
Roll forward/Cascade Report ...................................................................................................................... 42
45. Query Variables and Roll Forward Operation ......................................................................... 42
Miscellaneous ............................................................................................................................................. 42
46. Custom Groups and New Objects ........................................................................................... 42
47. Reference Variables and Shared Objects ................................................................................ 42
48. Variable naming convention ................................................................................................... 42
Appendices.................................................................................................................................................. 44
1. CDM Deployment on Multiple Environments............................................................................. 44
2. Restoring CDM database if it originated from a different application server ............................ 47
3. Encrypting/Decrypting ConnectionString.config ........................................................................ 49
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 databasename '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
5. Application Pool and Idle Time-out
Description: After installing the CDM Application Web Service, IIS by default sets the Idle Time-
out to 20 mins. This means that if the Application is not used (no active sessions), the
corresponding Application Pool for CDM will remain idle for at least 20 mins before reactivating
the session once again. This may add some delay in CDM due to session activation.
Best Practice: It is recommended to set the Idle Time-out value to 0. This will trigger the
Application Pool to re-active the session without any delay. See Steps below:
1. Determine Application Pool used by the CDM Web Service. This can be found in the
Website/Webservice properties.
2. Once determined, navigate to Application Pools. Find the CDM web services and click on
Advanced Settings.
7|Page
3. Once there, under Process Model, change Idle Time-out (minutes) to 0, as shown below:
8|Page
Security:
6. 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
7. 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.
8. 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
9|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 (%).
9. 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 Users 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):
10. 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)
10 | P a g e
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 dont 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:
11. 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.
12. 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:
13. 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.
11 | P a g e
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
14. 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.
15. 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.
16. 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.
12 | P a g e
17. 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.
13 | P a g e
Background: Microsoft PowerPoint

table cells do not have the capability for
the auto-fit feature for Shapes. See
below screenshot:
Microsoft Excel however, does have this

capability and it can be seen under the
cell property:
14 | P a g e
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.
18. Microsoft Excel Objects & Alignment Enforcment Setting
Description: If the Alignment enforcement setting is enabled in an Excel object, it will

automatically align the table and table cells to the setting specified in the Page Setup Object.
See Example below of such behaviour when the alignment is centered:
15 | P a g e
Best Practice: It is recommended to disable Alignment Enforcement setting on Excel objects

that do not require this customization. If the Excel table alignment (not cell alignment) is still
required, follow Best Practice #21 as it presents a scenario where margin enforcement from
Page Setup object may be utilized for Excel table alignment.
19. 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.
20. Microsoft Excel Objects: Padding Value
Description: Cell padding in an Excel object can be changed when generating a printable range
to a Word/PDF Document by specifying a value between 0.01 to Zero at the intersection of
##RS/##RE as shown below:
Special consideration must be taken when changing the value: The larger the value, the larger
the padding will be. This may cause tables to shift/break into the next page, if they are not set
up correctly.
Best Practice: It is recommended to leave that cell empty if there is no specific need to modify
padding to fit a certain size. The default value for padding, if no customized value is specified is
0.017 inches.
16 | P a g e
21. Microsoft Excel Objects: Custom Margins and Excel Tables
Description: If a custom margin is enforced in a CDM report through a Page Setup object, Excel
table margins may be affected in the following ways:
Columns of the table may cut off at a certain point due to the size of the Excel margin
versus the Word margin from Page Setup
Tables may only align to the left hand side of the margin but not the right side of the
margin
See screenshot below:
17 | P a g e
In the example above, the Income Statement table seem to only align to the left hand side.
Some reporting entities require that the table is also aligned at the right-side to the text
preceding the table in order to ensure that tables appear uniform when printed.
If the table is expanded in the Excel object to try to fit more columns, it may cut off part of the
table as shown below:
Excel Page Break View can be used to outline whether or not a table will be cut-off after it is
generated. This will introduce a dotted line:
18 | P a g e
Best Practice: Excel table generation does not automatically fit the table to the customized Page
Setup margins. This requires a manual process to first modify the Excel margin specified in the
Excel Object, then to adjust the actual table width in order to enforce the Page Setup margin, as
shown in the following steps:
1. Navigate to the Excel object, and change the Margin to 0 for all properties.
19 | P a g e
Note: This step should only be done to tables that will enforce margin from Page Setup object. If
no Page Setup object is found, the table will generate with 0 margins, and may yield undesirable
result:
20 | P a g e
2. Once the margin has been changed to 0, expand/retract the Excel columns to the desired size
in the Excel object. Excel pixels may be utilized here to standardize a fitment that meets the
need to align to both the left and right side of the custom margin from Page Setup.
21 | P a g e
Example 1: Column adjustment that exceeds the custom margin:
22 | P a g e
Example 2: Perfect Column adjustment to the text above and below the table
23 | P a g e
22. 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
Alternatively, you may use the word Var in-front of the range names that uses this string
Example: Var_Consolidate_Area
23. 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.
24. 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().
24 | P a g e
25. 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.
26. Hyperlinks in CDM
Description: Hyperlinks in CDM allows the user to reference Charts, Images and Excel named
ranges in Word and PowerPoint objects while allowing them to automatically update the
content should they change in the original source. The following is a simple guide that further
explains how to insert a hyperlink into CDM:
1. Adding a Chart
You can reference a chart from an Excel object, either in a Word or a PowerPoint object.
By default, the chart name is Chart 1.
To change the name, select the chart and go to Layout Chart Name.
1.1 - Adding a Chart to a Word object
Open the Word object and position the mouse where you want the chart to appear.
Here, select Insert Hyperlink:
25 | P a g e
Add the hyperlink in the Address bar. The hyperlink must be in this specific format:
cdm:chart:objectName:sheetName:chartName
It will import the chart at its original size.
You can edit the Text to Display bar. This text will appear in the Word object; the chart is not
visible in the Word object, but it appears when the document is generated.
Note: Automatically, all spaces will be converted to the Unicode name %20.
For formatting purposes, the chart can be place in a 1x1 table. The table must be resized to the
desired size, and the syntax will be: cdm:chart:objectName:sheetName:chartName?resize.
1.2 - Adding a Chart to a PowerPoint object
The syntax is the same as described above, for the Word object.
For formatting purposes, the chart can be placed in a 1x1 table, or a textbox.
2. Adding an Image
You can reference an image range from an Excel object, either in a Word or a PowerPoint object.
In the Excel object, you must define the image range using the ##IRS/##IRE variables. The range
can contain data or a graphic.
2.1 Adding an Image to a Word object

Open the Word object and position the mouse where you want the image to appear.
26 | P a g e
For formatting purposes, the image can be inserted in a 1x1 table, which must be resized to a
desired size.
Here, select Insert Hyperlink:
Add the hyperlink in the Address bar. Edit the Text to Display bar.
There are several syntaxes available, choose the one that fits the purpose:
cdm:customrange:objectName:sheetName?image imports an image range that contains data,
at its original size
cdm:customrange:objectName:sheetName?image&resize imports an image range that
contains data and sizes it to the container
cdm:customrange:objectName:sheetName?snapshot imports an image range that contains a
graphic, at its original size
cdm:customrange:objectName:sheetName?snapshot&resize imports an image range that
contains a graphic and sizes it to the container
27 | P a g e
2.2 Adding an Image to a PowerPoint object

The syntax is the same as described above, for the Word object.
3. Adding an Excel Named Range to a PowerPoint object
You can define a named range in an Excel object and then reference it in a PowerPoint object.
A named range can be added in Excel from Formulas Name manager New; or by directly
adding it in the Name Box, on the Formula Bar (where it says B3).
In PowerPoint, insert a Text Box and add the hyperlink:

cdm:range:objectName:sheetName:rangeName imports the range, at its original size
cdm:range:objectName:sheetName:rangeName?resize imports the range and sizes it to the
container.
28 | P a g e
27. 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
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.
29 | P a g e
28. 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
29. 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.
30. 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:
30 | 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 were 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 doesnt 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.
31 | 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 arent updated in the destination variable, causing the user
to see old numbers.
31. 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.
32. Automatic Refresh of HFM SmartView formulas
Description: Since the application server does not communicate with the HFM Add-in installed
on the users 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
32 | 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:
33. 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.
34. 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.
33 | 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.
35. 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.
36. 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.
37. 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.
34 | P a g e
38. 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.
39. 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
35 | 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.
36 | 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:
37 | 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.
38 | P a g e
40. 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
41. 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.
39 | P a g e
42. Configuring Excel Data Query Row Limit
Description: When inserting an External Excel File Data Query, the number of rows returned will
be limited to 1000 rows by default. If more than 1000 rows are required, this may be configured
in the CDM.config file found in the CDM Web Service directory. See the following steps:
1. Navigate and open the CDM.config file with Notepad:
2. Find ExcelRefresh queryResultMaxRows and modify the value to the desired limit:
Note: This restriction can be turned off by changing truncateOnQueryResultMaxRowsExceeded

to False. Although this is possible, it is not recommended. This is because it will leave the user
inclined to inserting thousands of rows that may not be needed and hence, may cause delay
with refreshing unnecesary data.
40 | P a g e
Report Generation/Validation
43. 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.
44. 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.
41 | P a g e
Roll forward/Cascade Report
45. 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
46. 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:
47. 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.
48. 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,
42 | 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.
43 | 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:
44 | P a g e
45 | 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:
46 | 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\key.txt"
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\key.txt"
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.
47 | 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!
48 | 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.
49 | P a g e

Cognos Disclosure Management 10 2 Best Practice Document Jan 08 2013 PDF

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Cognos Disclosure Management 10 2 Best Practice Document Jan 08 2013 PDF

Transféré par

Droits d'auteur :

Formats disponibles

IBM COGNOS DISCLOSURE

MANAGEMENT 10.2 BEST Best Practices ver.

PRACTICES DOCUMENT VER. 2.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 databasename '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

5. Application Pool and Idle Time-out

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

10. Importing Groups from AD with Auto-Registrable option

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

12. Template Workflow Design

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

Report and Object Management:

13. Importing Objects

14. Deleting Bulk Objects

15. Object Hierarchy and Delete Behaviour

16. PDF Objects

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

18. Microsoft Excel Objects & Alignment Enforcment Setting

Description: If the Alignment enforcement setting is enabled in an Excel object, it will

Best Practice: It is recommended to disable Alignment Enforcement setting on Excel objects

19. Microsoft Excel Objects: External Links

20. Microsoft Excel Objects: Padding Value

21. Microsoft Excel Objects: Custom Margins and Excel Tables

See screenshot below:

Example 1: Column adjustment that exceeds the custom margin:

22. Microsoft Excel Objects: Reserved Ranges

23. Microsoft Excel Objects: Add-in Mode

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

26. Hyperlinks in CDM

1.1 - Adding a Chart to a Word object

It will import the chart at its original size.

1.2 - Adding a Chart to a PowerPoint object

2.1 Adding an Image to a Word object

Here, select Insert Hyperlink:

2.2 Adding an Image to a PowerPoint object

3. Adding an Excel Named Range to a PowerPoint object

In PowerPoint, insert a Text Box and add the hyperlink:

27. Resolving Microsoft Excel Range Variables in Microsoft Word Objects

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

28. Page Setup and Office Theme Fonts

Office 2007 Office 2010

29. Object Properties: Break Type

30. Variable Chaining

Symptoms of Variable Chaining

Description: CDM supports the following HFM SmartView custom formulas:

32. Automatic Refresh of HFM SmartView formulas

Data Source/Query Management:

33. TM1 Data Source vs. TM1 Perspective in CDM

Description: CDM provides Cognos TM1 integration in two ways: