Document

Canned Reports

The canned reports module is designed to create specific reports that are commonly used. This module was created to quickly allow MetaManager^TM customers to see value and get insight out of their environment right out of the box. Canned Reports allow you to document various components of your Cognos BI environment including: dispatcher and services settings from within the System tab of Cognos Administration, configuration settings from Cognos Configuration, and Cognos security. It will also allow you to validate datasources in bulk and view all scheduled content within your Cognos BI environment.

The PDF output is designed as a business document to review, with bookmarks for easy navigation. Excel is laid out in a tabular format with auto filtering, and the xml is designed so that you can incorporate this data with other systems.

Access rights are very time consuming to produce and query intensive. Access rights produce many pages of documentation. We provide a tree representation of the public folder for each user. Documenting access rights for all of the accounts in the contents store will likely produce a very large output file that is difficult to manage and navigate, in addition to documenting access rights we limit access rights to just packages and folders. The purpose of this is to simplify the tree representation of the public folders by only documenting access rights for packages and folders but excluding objects like reports. We recommend that you use this setting if your Cognos environment utilizes inheritance security policies and does not have explicit security policies defined at the object level.

Navigating and understanding the Canned Reports UI

There are several different Canned Reports to help you understand you Cognos environment.

Configuration

IBM Cognos Administration produces an audit of Cognos Administration Configuration for each dispatcher and service listed in the system tab of the Cognos Administration console. This report supports the following outputs: PDF, XML, and XLS.

IBM Cognos Configuration produces an audit of all Cognos Configuration settings for the selected cogstartup.xml file. This report supports the following outputs: PDF, XML, and XLS.

Audit Account Security Audit produces an audit of all or selected Accounts, Groups and Roles. The audit contains general information about the object, a list of groups and roles the object is directly and indirectly a member of and a list of objects the account, group or role has access to. This report supports the following outputs: PDF, XML, and XLS.

Include Access Rights – In order to include the access rights of each role, class and account in the resulting documentation (i.e. who can see what, and what level of access they have), use the Document Access Rights check box.

NOTE: This option requires Content Documenter to cycle through the entire content store in some cases more than once in order to generate this information, so selecting this option will result in longer documentation times.

Include Datasources – In order to include the data source access in the resulting documentation, use the Include Datasources check box.

Limit output to only selected Account, Groups & Roles – This option will allow the user to only document the Users, Groups, and Roles they wish to drag and drop form the Portal Tree to the grid area.

Scheduled Content extracts detailed schedule information for all scheduled content. This report supports the following outputs: PDF, XML, and XLS.

Compare Environments provides a detailed list of objects that are different between two Cognos environments, can be filtered on object type, and can include security if requested (this can increase report runtime)

License Audit generates an Excel output of the IBM Cognos license usage and capabilities.

Stored Outputs generates an Excel output that includes the location, size, and date created for all report outputs in the content store.

Security Concerns provides an audit of security inheritance and direct account access.

Validation DataSource Validation produces a audit of all Datasources in the environment and their validation status. This report supports the following outputs: PDF, XML, and XLS.

Assessment Report Validation validates and documents validation of reports, report views and shortcuts.

Report Runtime produces an audit of report runtimes from the audit database (must have audit database connected to MetaManager via the IBM Cognos Connection in Tools > Options).

Account Login produces an audit account login from the audit database (must have audit database connected to MetaManager via the IBM Cognos Connection in Tools > Options).

Object Statistics produces report of size and count statics for objects in your Cognos environment.

Embedded SQL finds all reports with embedded SQL.

Content Documenter

The Content Documenter Module provides detailed record keeping of the contents of your IBM Cognos Connection environment by documenting desired content into a variety of formats, including:

• XML

• PDF

• Excel

• CSV

• HTML

• Can be sent directly to a database.

Generate Detailed Documentation

To begin using Content Documenter, you must:

1. Identify the objects you wish to document.

2. In the Specify an output file box, click the Browse button to select an output location and output type. Output types include HTML, PDF, XML, XSL, CSV and Text.

   NOTE: You do not need to have Adobe Acrobat installed to produce PDF files, however, to open the files after they are generated you must have Adobe Acrobat Reader.

3. Filter objects if needed.

4. Select the information you wish to document.

5. Document the results.

NOTE: PDF and HTML output formats include indexed table of contents for easy navigation.

Selection Options Filter

The filter option provides two methods to scope the objects from your selection:

Depth – Select the depth you want to backup, to include this item only or all subfolders.

Filter – Click the filter image to filter on sub-objects that is required to backup (it defaults to backup all types). Selecting only reports or only security objects based on a specific use case will result is small backups and more flexibility to the user.

Apply to all rows – allows the user to make the criteria selection once and apply the filter to all objects in the current grid area

Information to document

Using this portal tree the user can select what information to document.

Content Documenter Processing

As Content Documenter is being executed, the area at the bottom will indicate the status of the documentation.

1. The “Rendering content store object list” count will increment until all objects have been retrieved.

2. The document will open in the appropriate application once complete.

NOTE: Since Content Documenter does not know up front how many objects are to be processed an accurate percentage of completion cannot be determined. Therefore, the number of objects already processed will be displayed to indicate that the module is still working and to provide insight as to how fast the module is processing.

Report Lineage

Report Lineage allows a user to trace a data source, data module, exploration (dashboard) or report to the specific tables and columns included related objects.

Drag a data source, data module, exploration (dashboard) or report from the portal tree over to the editing area on the right to load related data source references.

Expanding the resulting tree reveals related tables, reports, and deployment references.  Further expansion of objects will show table and column names as well.  When selected, a table or column name will highlight related reports.  Shown above, you can see the Delta column is included in three reports. 

To document the report lineage, click the “Document” button in the lower right corner.  The resulting Excel file includes all of the information shown on screen, as well as full data expressions.

Content Size

Content Store Size is designed to give users the ability to view the size of any object within their environment. The user can quickly go through the tree view and select any content they wish to view, from either the Public Folders or their Directory.

NOTE: The Graphical interface is not supported in the 64-bit version.

Navigating and understanding the Content Store Size UI

The figure below is the entire interface for Content Store Size. There are four basic sections to this module:

1. Portal Tree

2. Canvas Area

3. General Tab

4. Details Tab

Portal Tree

The portal tree in Content Store Size behaves differently than any other module. Note that objects in the tree have numbers in parenthesis indicating the size of the object. Also, the content is not displayed in alphabetical order, instead it is displayed in order from largest to smallest based on the size of the content. When an object is selected in the portal tree Content Store Size will load the information into a pie chart in the canvas area and show details on the sidebar to the right.

Canvas Area

The canvas area gives a visual diagram of how a particular object is divided up. The object name that is selected is displayed in the top left corner of the canvas area, and the children of the object selected are displayed in the pie chart. The pie chart is interactive and can be used to drill through objects. By double clicking a child object it will become the parent object and all of its children will then be displayed in the pie chart. There is a hover-over screen tip as well with the pie chart. When hovering over an object it will display:

• Name of the object

• Object type.

• Total Size

• Object Count (number of sub objects)

By clicking once on a slice of the pie will detach it from the rest of the chart giving details of just that single piece in the sidebar to the right. Clicking a second time will replace the slice.

General Tab

The General tab is located in the upper right corner and displays general information of the object that is selected. The general information changes as a user selects a piece of the pie or drills through the content. The information displayed is:

• Name of the object

• Object type.

• Number of sub objects

• Total Size

Details Tab

The Details tab is located just underneath the General tab and displays more detailed information of the object that is selected. The detailed information changes as a user selects a piece of the pie or drills through the content. The information displayed is the child information of the selected object. It gives all types of the sub objects, how many of each type there is, and the total size of each type.

NOTE: Content Store Size data can be exported to PDF or HTML by simply selecting the buttons from the tool bar. Data that is selected and visible within the main grid will be documented.

Model Documenter

The Model Documenter provides detailed record keeping of the contents of Cognos Framework Manager models by documenting desired content into a variety of formats, including:

• HTML

• PDF

• XLS (List or Tabular format)

• XML

• ANSI Text

Users may document the entire model or any number of selected objects and attributes.

NOTE: If Excel (.xlsx) is selected as the output type you have the option to generate the older list style report, or you may choose the option to use a tabular format for easier filtering, sorting and analysis in Excel.

Generate Detailed Documentation

To begin using Model Documenter, you must:

1. Determine the desired Framework Manager model.

2. Identify the content you wish to document.

3. In the text box on the top right, click the Browse button to select an output location and output type. Output types include HTML, PDF, XLSX and Text.

NOTE: You do not need to have Adobe Acrobat installed to produce PDF files, however, to open the files after they are generated you must have Adobe Acrobat Reader.

4. Select the desired level of detail for Attributes by choosing from the various items in the middle right pane.

   NOTE: For more information on the various Attributes, please refer to the IBM Cognos product documentation.

5. Select the desired locales to be output by choosing from the various items in the right pane.

   NOTE: The available locales will depend on the locales used in the selected Framework Manager model.

6. Document the results.

   Based on the selected objects and attributes selected, varying detailed information is given in the output document.

   NOTE: PDF and HTML output formats include indexed table of contents for easy navigation.

Use Filter Options

Model Documenter Processing

As Model Documenter is being executed, the area at the bottom will indicate the status of the documentation.

1. The status bar will increment until all objects have been retrieved.

2. The document will open in the appropriate application once complete.

Report Documenter

The Report Documenter Module provides detailed record keeping of reports within any IBM Cognos Connection environment by documenting desired reports into a specific folder. All reports will be output to PDF files, within the selected folder.

Documenting a Report

• Report Documenter only Documents IBM Cognos Report Studio Reports.

• The output of the report can be in PDF, HTML, or XML format.

• The folder structure can be in Flat or Tree.

• Begin by dragging reports, folders, packages or accounts to the processing grid.

  • Container objects, such as folders, will be evaluated to a list of reports.

• By selecting the folder icon in the top right of the canvas it will prompt the user to select or create a new folder to save the report documentation.

Include Lineage

The Include Lineage option will pull information of the actual queries within the model. This will be information such as the Query Namespace, Query Subject, Query Item, etc. An example of this output is below. The lineage can be found in all output formats including the Query Item Report.

Produce Query Item Report

The Query Item Report option creates an Excel file containing specific query details for each of the selected reports. An example of this report is shown below.

Display Company Logo in Documentation

Change the logo file(logo.gif) in MetaManger's "install_path\BSP\MetaManager^TM" folder.

We suggest renaming the current file to backup/save it. Name the logo file logo.gif, and make sure the size is ~210(w)x86(h). The height is currently more important than the width for PDF rendering.

Report Search

The Report Search module provides a powerful and intuitive interface to perform a search across a selectable group of reports. This new module is a trimmed down version of the Find / Replace module which is designed for performing fast searches for impact analysis. For example, this module simplifies the use case to find all reports using a specific data item.

Search Options

The Options tab allows users the ability to specify one search criteria to be performed on the selected content.

Search Text - This represents the text to search for within the specification(s).
Location - This represents the scope of the specification search for. For more information on this field, see the section later in this chapter.
Use Regular Expression - When selected, the Search Text will be run through the .NET Regular Expression Engine. This option allows you to specify more complex search strings using regular expressions, which allow searching for patterns rather than static text.

NOTE: This is an advanced feature. Refer to http://en.wikipedia.org/wiki/Regular_expression for more information on Regular Expression. In addition, there are a number of tools available to help author RegEx (i.e. Expresso - http://www.ultrapico.com/Expresso.htm, a free download that comes with a tutorial and lots of samples).

NOTE: It is recommended that users copy report specifications and use a utility like Expresso to build and debug the regular expression.

Case Sensitive – This specifies whether the Search syntax should be treated as case sensitive.
Model Browser– This icon can be selected, which will prompt the user to select a package. Once a package is selected the user can navigate and select a DataItem to search for. The search text and location options will automatically be populated based on the user’s selection.

NOTE: For some use cases the user may need to navigate to areas of the portal to copy text such as an object’s SearchPath or account’s ID, to be used as search text. The property grid beneath the portal tree provides quick access to a number of properties which may be helpful when searching for text entries.

Processing Results

As Report Search is being executed, the report icon on any given Object Row will change to an hourglass while an Object Row is being processed.

The “Impacted” column will let the user know if the search criteria they provided is identified within the reports selected in the top pane.

Screen Tip Generator

The power of the metadata created within the Framework Manager model is released to the user by automatically bringing the metadata to selectable reports in the form of screen tips. The Screen Tip Generator will populate report column headings with the metadata previously created within the Framework Manager model creating a completely integrated metadata environment.

NOTE: It is strongly recommended that before any changes are made to reports using this and any other module of MetaManager^TM you use the Create a Backup button on the module toolbar to back up the content pre-change.

Apply Screen Tips to Reports

To begin using Screen Tip Generator, you must:

1. Ensure that Framework Manager query items have Screen Tip attributes populated within the model. You can use Framework Manager and / or Meta editor to populate this attribute.

2. Ensure that the associated Package(s) have been published.

3. Identify the content you wish to apply screen tips to.

4. Apply the screen tips.

NOTE: Screen tips are applied to the HTML output of Report Studio objects only.

Processing

As Screen Tip Generator is being executed, the report icon on any given Object Row will change to an hourglass while an Object Row is being processed.

1. A triangle marker indicates which step the object row is processing.

2. The validation results are represented in the Current Status field with an icon indicating the status. See below for more information.

Preview

The processing steps for Preview are:

1. The selected report specifications (may come from cache) are loaded into memory.

2. The specifications are then validated against the applicable package in the Content Store.

3. Each Object Row is executed sequentially.

   1. Check to see if an existing screen tip exists on each data item.

   2. If the new screen tip is empty, remove the existing screen tip if applicable.

   3. If the new screen tip matches the existing one, do nothing.

   4. If the new screen tip is different from the existing one, remove the existing one. Then replace the old screen tip with the new screen tip.

4. The new specifications are then validated against the applicable package in the Content Store.

NOTE: When Preview is used rather than Update, any desired Object Row can be selected, and the specification can be previewed through the right-click menu. This allows for a visual comparison to the stored specification in the Content Store, which can be run through the right-click menu, Run option.

They can also be previewed textually using the Diff Changes right-click menu.

Update

The processing steps for Update are:

1. If the Preview has been performed, execute steps 1 – 4 above.

2. Save the modified specifications in place of the current specification within the Content Store.

Validation Results

The following table lists the possible validation results.

Icon	Validation Result	Description
	OK	Report validated with no problems.
	Exception	Some type of anomaly occurred. Check the Information section to see what exceptions caused a failure.
	Prompt	The report requires prompt answers that could not be supplied as part of the validation processing. All other aspects of the report (namely the syntax / specification) are OK.
	Warnings	The report validation was able to proceed, but with errors that may affect the report integrity. Check the Information section to see where the validation encountered errors.
	Errors	Report validation failed. Check the Information section to see where the validation encountered errors.

An explanation of validation results