IBM COGNOS DISCLOSURE MANAGEMENT 10.2 BEST 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

Best Practices ver. 2.0

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

Contents
Architecture/Installation:.............................................................................................................................. 4 1. 2. 3. 4. 5. Click Once Deployment. ................................................................................................................ 4 Application Server Deployment. ................................................................................................... 4 CDM Deployment on Multiple Environments............................................................................... 5 CDM Client Deployment ............................................................................................................... 6 Application Pool and Idle Time-out .............................................................................................. 7

Security: ........................................................................................................................................................ 9 6. 7. 8. 9. 10. Workflow Object Security ............................................................................................................. 9 Change Reference and Object Security ........................................................................................ 9 Password Complexity .................................................................................................................... 9 Automatic Login .......................................................................................................................... 10 Importing Groups from AD with Auto-Registrable option ...................................................... 10

Workflow: ................................................................................................................................................... 11 11. 12. Bulk Workflow Operation ....................................................................................................... 11 Template Workflow Design..................................................................................................... 11

Report and Object Management: ............................................................................................................... 11 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. Importing Objects ................................................................................................................... 11 Deleting Bulk Objects .............................................................................................................. 12 Object Hierarchy and Delete Behaviour ................................................................................. 12 PDF Objects ............................................................................................................................. 12 Microsoft PowerPoint Objects ................................................................................................ 13 Microsoft Excel Objects & Alignment Enforcment Setting ..................................................... 15 Microsoft Excel Objects: External Links .................................................................................. 16 Microsoft Excel Objects: Padding Value ................................................................................. 16 Microsoft Excel Objects: Custom Margins and Excel Tables ................................................... 17 Microsoft Excel Objects: Reserved Ranges ............................................................................. 24 Microsoft Excel Objects: Add-in Mode ................................................................................... 24 Microsoft Excel Objects: Using Now(), Workday () formulas in Microsoft Excel calculations 24 Microsoft Excel Objects: Image Range Variables (##IRS/##IRE) ............................................. 25 Hyperlinks in CDM ................................................................................................................... 25

2|Page

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012
27. 28. 29. 30. 31. 32. Resolving Microsoft Excel Range Variables in Microsoft Word Objects ................................. 29 Page Setup and Office Theme Fonts ....................................................................................... 30 Object Properties: Break Type ................................................................................................ 30 Variable Chaining .................................................................................................................... 30 Working with Microsoft Excel objects and HFM SmartView formulas ................................... 32 Automatic Refresh of HFM SmartView formulas .................................................................... 32

Data Source/Query Management:.............................................................................................................. 33 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. TM1 Data Source vs. TM1 Perspective in CDM ....................................................................... 33 Cognos Controller in CDM....................................................................................................... 33 Cognos For Microsoft Office/Cognos Analysis for Microsoft Excel in CDM ............................ 34 Cognos For Microsoft Office Search functionality and Office 2003 ........................................ 34 Cognos For Microsoft Office behaviour with multiple Microsoft PowerPoint Instances ....... 34 Editing External Microsoft Excel File Structure ....................................................................... 35 TM1 Queries and Aliases......................................................................................................... 35 Data Source Connectivity Requirements for the Application Server: ..................................... 39 Using an External Microsoft Excel File Source located on a network drive on User Machine 39 Configuring Excel Data Query Row Limit ................................................................................ 40

Report Generation/Validation .................................................................................................................... 41 43. 44. Validation Report .................................................................................................................... 41 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. 47. 48. Custom Groups and New Objects ........................................................................................... 42 Reference Variables and Shared Objects ................................................................................ 42 Variable naming convention ................................................................................................... 42

Appendices.................................................................................................................................................. 44 1. 2. 3. CDM Deployment on Multiple Environments............................................................................. 44 Restoring CDM database if it originated from a different application server ............................ 47 Encrypting/Decrypting ConnectionString.config ........................................................................ 49

3|Page

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012
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\CognosDMServer\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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012
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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012
5. Application Pool and Idle Time-out Description: After installing the CDM Application Web Service, IIS by default sets the Idle Timeout 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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

3. Once there, under Process Model, change Idle Time-out (minutes) to 0, as shown below:

8|Page

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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 (2011)

Cascade

Cascade Report (2011)

Roll Forward

Roll Forward

Master Report (2012)

Cascade Report (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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012
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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012
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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012
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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

Example 1: Column adjustment that exceeds the custom margin:

22 | P a g e

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

Example 2: Perfect Column adjustment to the text above and below the table

23 | P a g e

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

45 | P a g e

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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\CognosDMServer\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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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

IBM Cognos Disclosure Management 10.2 Best Practices Document ver. 2.0 2012

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