A Field Guide to Tivoli Common Reporting V3

A Field Guide
to
Tivoli Common Reporting V3
Bjoern W. Steffens
IBM Certified Consulting IT Specialist
&
IBM Switzerland Ltd.
Binningerstrasse 2
CH–4142 Münchenstein
+41 79 278 92 18
[email protected]
© Copyright IBM Corporation 2014
This document is the sole property of IBM Switzerland Ltd. No part of this
document may be reproduced in any form or by any means - electronic, mechanical,
photocopying, recording or otherwise without the prior written permission of
IBM Switzerland Ltd.
A Field Guide to Tivoli Common Reporting V3
Document Control
Document Tag
Tag Metric
IBM document author and owner
Bjoern W. Steffens
Document inception date
March 1st, 2012
Last update
29.01.2014 17.47
File name
A Field Guide to Tivoli Common Reporting v03r01 20140129
Revision History
Revision
Date
Author
Summary of Changes
v01r01
10.03.2012
Bjoern W. Steffens
First version.
v01r02
20.03.2012
Bjoern W. Steffens
General clarifications and expanding
on how to save reports to disk.
v03r01
01.29.2014
Bjoern W. Steffens
Adapting the document for Tivoli
Common Reporting V3 and expanding on operational aspects.
Contributors
Name
Title
Dan Krissell
Tivoli Common Reporting Architect
Gireesh Govind
Tivoli Common Reporting Release Manager
Preethi C Mohan
Tivoli Common Reporting Chief Programmer
Pradeep K Sudarshan
Tivoli Integrated Portal L3 Manager
Bhanu P Velampati
Tivoli Common Reporting Technical Lead WW L3 Support
Approvals
Name
Title
Dan Krissell
Tivoli Common Reporting Architect
Gil Arnold
Tivoli Common Reporting Release Manager
Preethi C Mohan
Tivoli Common Reporting Chief Programmer
Pradeep K Sudarshan
Tivoli Common Reporting Technical Lead WW L3 Support
Bhanu P Velampati
Tivoli Common Reporting Technical Lead WW L3 Support
Bjoern W. Steffens
IBM Consulting IT Specialist
Distribution
Name
Title
Internal
Page 2/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Table of Content
1. TCR V3 Key Enhancements
8
1.1. Mobile Components
10
1.2. Dynamic Query Mode and JDBC Files
13
1.3. Data Modeling with a DQM Source
14
2. TCR V3 in the Context of Jazz For Service Management
15
2.1. Administration Services
15
2.2. Dashboard Application Services
16
2.3. Registry Services
16
2.4. Reporting Services
17
2.5. Security Services
17
3. Tivoli Common Reporting Component Overview
18
3.1. Jazz for Service Management
19
3.2. Cognos Framework Manager
20
3.3. Cognos Administration
21
3.4. Cognos Query Studio
22
3.5. Cognos Report Studio
22
3.6. Cognos Event Studio
23
3.7. Cognos Workspace
25
3.8. Cognos Workspace Advanced
26
3.9. Cognos Active Reports
27
4. Deployment Considerations
28
4.1. Migration Routes
28
4.2. Architecture29
4.3. A Report Development Architecture
30
5. Operations31
Page 3/73
5.1. Disaster and Recovery
31
5.2. Backup and Restore
32
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
5.3. Managing Tivoli Provided Report Packages
33
5.4. BIRT Report Packages
33
5.4.1 Managing BIRT JDBC Drivers
33
5.4.2 Manually Importing Report Packages
34
5.4.3 Data Source Configuration
35
5.5. Cognos Report Packages
36
5.5.1 Managing Data Sources for the TCR/Cognos Server
36
5.5.2 Manually Importing Report Packages
37
5.6. Scheduling and Distributing Reports to Disk
40
5.6.1 CLI Report Scheduling
40
5.6.2 GUI Report Scheduling
43
5.6.3 Configuring Jobs & Schedules
44
5.6.4 Saving Reports To Disk
45
5.6.5 Saving Reports Outside Cognos
46
5.6.6 Saving Reports Inside Cognos
48
5.6.7 Managing Disk Content
50
5.7. Restricting Access to Cognos Reports
53
5.8. Recommended Report Development Practice
59
5.9. Cognos Report Templates
60
5.10.Creating a System Wide Report Templates
61
5.11.Identifying System Bottlenecks
62
5.11.1Turning on Cognos Auditing
62
5.11.2Cognos Monitoring
66
6. Common Issues
70
6.1. Less Recent Observations Still Applicable
70
6.2. New Observations
71
7. References73
Page 4/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Table of Figures
Figure 1. TCR V3 high availability and load balanced architecture
Figure 2. IBM Cognos app on an iOS Tablet
Figure 3. JAR files required for dynamic query mode on a Suse 11 Linux server
Figure 4. JDBC data source connection test
Figure 5. Dynamic query mode framework manager project
Figure 6. Jazz for Service Management service components
Figure 7. Working with Cognos
Figure 8. Tivoli Common Reporting and Jazz for Service Management
Figure 9. Cognos data model best practice architecture
Figure 10. Cognos Framework Manager ITM V6.3 OS agent data model
Figure 11. Cognos Administration
Figure 12. Cognos Query Studio
Figure 13. Cognos Report Studio
Figure 14. Cognos event studio configuration
Figure 15. Cognos workspace sample
Figure 16. Cognos Workspace Advance sample
Figure 17. Cognos Workspace Advance sample
Figure 18. Active report sample
Figure 19. Tivoli Common Reporting migration paths
Figure 20. Tivoli Common Reporting deployment scenarios
Figure 21. Report development architecture
Figure 22. BIRT JDBC driver location.
Figure 23. ITPA OS BIRT report package content.
Figure 24. BIRT report package import.
Figure 25. BIRT report package in Cognos Connection
Figure 26. BIRT scripted data source change.
Figure 27. Successful compatible and JDBC(DQM) Cognos data source connection test.
Figure 28. Tivoli report package content for Cognos reports
Figure 29. Tivoli report package to be loaded on the TCR server
Figure 30. Tivoli report package location on the TCR server
Figure 31. Cognos report example
Figure 32. Cognos trcmd distribute example
Figure 33. Cognos job definition example
Figure 34. Cognos schedule definition example
Figure 35. Cognos Server external location to save reports to
Figure 36. Cognos Administration report save location
Figure 37. Parameters and results end users saving reports to disk
Figure 38. Cognos Server save inside configuration
Figure 39. Desired Cognos Server save inside configuration save results
Figure 40. CM.OUTPUTLOCATION and CM.OUTPUTSCRIPT configuration
Figure 41. Cognos output versions saved to disk
Figure 42. Cognos output script folder structure requirements
Figure 43. Cognos output script folder with recovered file names.
Figure 44. TIP and Cognos security system interaction
Figure 45. Recommended report development process
Figure 46. Re-using layout components
Figure 47. Clearing the Internet Explorer cache
Figure 48. Cognos database log source
Figure 49. Cognos audit database
Figure 50. Audit tree selection
Figure 51. Audit target object
Page 5/73
IBM Switzerland Ltd.
9
12
13
14
14
15
18
19
20
21
21
22
23
24
25
26
26
27
28
29
30
33
34
34
34
35
37
37
38
38
39
40
44
44
46
47
48
48
49
49
50
52
52
53
59
60
62
63
64
64
65
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Figure 52. Figure 53. Figure 54. Figure 55. Figure 56. Figure 57. Figure 58. Page 6/73
Audit object logging level
Cognos report auditing data
Audit report sample - hourly average report execution time
Cognos internal monitoring system
TCR/Cognos monitoring concept
WebSphere application server summary
WebSphere application health
IBM Switzerland Ltd.
65
65
66
67
68
69
69
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Preface
This document provides an overview of the general aspects that must be mastered working
with Tivoli Common Reporting V3 (TCR) in a production environment. Operating a TCR solution you need to be able to manage both BIRT and Cognos reports in order to deploy the
Tivoli provided reports in an enterprise environment. There are Tivoli products still shipping
BIRT reports and that is why it is essential to be able to manage both report package types.
As of TCR V2, the BIRT GUI interface for managing reports is no longer made available. This
means that BIRT report configuration activities takes place from the command line. The most
typical actions you need to carry out using the trcmd tool are:
•
Import a BIRT report package
•
Set the data source for one or more BIRT reports
The Cognos reports are managed from the GUI leveraging Cognos Connection or using the
trcmd tool. Importing and managing Cognos reports is intuitive and generally does not provide any particular challenges. Scheduling and writing Cognos reports to disk does require
some thought and effort in order to provide a complete solution. The reason here is that
Cognos write the reports to disk with a very long serial number. There is however a helper file
provided on disk together with the report, assisting in renaming and/or processing a particular report further.
It is the objective of this paper to provide a comprehensive overview how to manage the various report types and also what you need to consider if you want to provide your own reports.
Providing custom reports can be a simple task if the provided Cognos Data model can be
leveraged. It can however become a more complex project if a Cognos Data Model has to be
designed and developed prior to developing the reports.
The document mention both BIRT, Cognos, TCR/BIRT and TCR/Cognos. In general the product
leveraged is Tivoli Common Reporting or TCR. TCR supports BIRT reports and here TCR/BIRT
or BIRT is used interchangeably. TCR also support Cognos reports and here TCR/Cognos or
Cognos is used interchangeably. TCR/Cognos also refers to the Cognos server specific components that are installed together with the TCR server. These Cognos components do not
require any specific installation steps or check marks. As well as the BIRT server components,
the Cognos server components are installed as part of the overall TCR server installation.
There are scenarios requiring you to install multiple TCR servers. This is not a typical setup but
is required to provide high availability and load balancing in a more complex environment.
In short, TCR provides both the BIRT engine and the Cognos engine. Both report types are
run and scheduled using the same process providing ease of use and hiding the underlying
technology components. TCR V3 provides Cognos V10 report engine and report development
tools.
This document does not cover any parts of the TCR server installation process and assumes
the TCR server has been installed and configured accordingly. A Suse Linux 11 64 bit installation with a DB2 database server has been used to provide the examples in this document.
Page 7/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
1. TCR V3 Key Enhancements
This list outlines the key and most prominent enhancements made to Tivoli Common Reporting V3. There are both changes to the underlying technology and graphical components used
to build and deliver reports. The hidden technology updates provides better performance
and scalability of the reporting server.
Page 8/73
•
TCR is now part of the IBM Jazz for Service Management platform. TCR V3.1 became
generally available March 8, 2013 with ITM 6.3. This new delivery model allow products
to break its dependency on a particular Tivoli Integrated Portal version. The advantage
is increased flexibility providing updates for various products independently having
implemented Jazz for Service Management.
•
Cognos V10.2 Components. The Cognos report engine, Cognos Connections and Cognos Framework Manager have been upgraded to version 10.2
•
Dynamic Query Mode (DQM) with support for JDBC files and an additional new 64 bit
report engine. When creating new reports, the 64 bit report engine can be used providing more scalability and performance. It is recommended to implement report packaged based on DQM when there are large, complex and many reports scheduled to run
in parallel. A 64 bit operating system deployment is required in order to use DQM.
•
Mobile add-on. A mobile interface has been added to the Cognos Report Engine. It is
now possible to navigate to the TCR server using a tablet browser and run reports. For
iOS there is also the “IBM Cognos” App in the appstore.
•
Report Workspaces. A report workspace is a report canvas where you can drag and drop
objects from other existing reports. A report workspace can be viewed as a report dashboard where the end user is designing the content without the assistance of an expert
report author.
•
Active Reports. A Cognos Active Report is a stand-alone, self-contained file. This allows
users to fully interact with all of the content in their reporting application without being dependent on connectivity to their IBM Cognos BI server. Disconnected reporting
simplifies report distribution and consumption within an organization and makes BI
content readily available to external partners and customers.
•
Flat file support for Report Studio. It is now possible to enrich report data on a workstation using a local file. This is a very useful feature for one-off and rare report requirements.
•
Event Studio. The Cognos event studio can be used to analyse data before a report is
executed. For instance if an incident report is to be issued once a week but there are no
incidents, the report will not be executed.
•
New charting engine. The new charting engine provides smooth lines, better 3D capabilities, various trend lines and many other features.
•
More scalable with a DB2 out of the box content store. The Cognos Content Store is no
longer supported on Derby. A DB2 server is provided as part of the installation and the
Cognos Content Store database will be hosted on it. This allows for better performance
and scalability for large and complex report deployment projects.
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
•
The scalability and high availability architecture has changed. In previous versions the
Cognos report engine and the Cognos UI components could be installed on two or
more servers for load balancing and high availability. In TCR V3 the vertical scalability is
provided by increased performance in the Cognos Report Engine. Vertical scalability is
provided by installing several Jazz for Service Management server with the TCR report
component with a load balancer in front.
Report Users
HTTP Load Balancer
Jazz for
Service Management
#1
LDAP
Content Store DB
Jazz for
Service Management
#2
Report
Data
Source
Figure 1. TCR V3 high availability and load balanced architecture
Page 9/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
1.1. Mobile Components
The mobile components need to be installed and can be found on the Jazz for Service Management installation media.
•
Locate the response.ats and response_fp.ats in the product installation directory. For a
Suse Linux 64bit system the files will be in this directory:
/opt/IBM/JazzSM/reporting/mobile/response.ats
Edit these files and set “I Agree=y” in the IBM License Agreement and Non IBM License
Agreement fields.
Title=IBM License Agreement
I Agree=y
Title=Non IBM License Agreement
I Agree=y
•
Run the installMobile.sh and install the mobile components. The installMobile.{ bat | sh }
is located in the actual product installation path.
> /opt/IBM/JazzSM/reporting/mobile/installMobile.sh $image_path/ITCR_3.1_FOR_LINUX_ML/
CognosMobile $jazzuser $jazzpwd
•
Start a browser on your mobile device and navigate check that the mobile interface is
running
http://jazzserver:16310/tarf/m/index.html
•
Page 10/73
Download the IBM Cognos app from the Apple App Store and connect it to the IBM Jazz
for Service Management Server
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Page 11/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Figure 2. IBM Cognos app on an iOS Tablet
Page 12/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
1.2. Dynamic Query Mode and JDBC Files
Dynamic Query Mode or DQM is the new 64 bit report engine leveraging more resources
on the system it runs. It also provides various new features. Read more about all the features
here.
DQM provides the 64 bit report engine if TCR has been installed on a 64 bit system. The 64 bit
report engine provides improved report performance in demanding environments that involve the execution of multiple reports simultaneously, large data sets, and complex reports.
This new report engine leverages the JDBC files. Older report packages will continue to use
the full database client or ODBC drivers. Existing packages cannot use DQM unless re-designed.
When you install and configure your TCR server you need to place the jar files from your db
server in the following directories and re-start it.
../JazzSM_Home/reporting/cognos/webapps/p2pd/WEB-INF/lib
../JazzSM_WAS_profile/profile/installedApps/localhostNode01Cell/IBM Cognos.ear/p2pd.war/WEB-INF/lib
The illustrations below shows where the DB2 jar files have to be copied to on a Suse Linux 11
64 bit system. There are already copies provided but the versions or driver types may not be
suitable for your database installation and may need to be replaced. An indication you should
consider replacing the drivers files could be continuous error messages about the UID and
Password not being correct when testing the JDBC data source in Cognos Administration.
Note: The jar files for other database types are to be copied to the same directories mentioned
above.
Figure 3. JAR files required for dynamic query mode on a Suse 11 Linux server
Page 13/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
The illustration below shows a data source configuration test on a TCR server where the jar
files for DQM have been provided. There is no DB2 client installed on this system.
This server in its current configuration will not run any existing or old report packages. It will
only provide the 64 bit report engine for new report packages having the “Dynamic Query
Mode” enabled. Note that the “Failed” status for the compatible query mode is expected here
as the database client has not been installed on the system.
Figure 4. JDBC data source connection test
1.3. Data Modeling with a DQM Source
When you use the Cognos Framework Manager to model data leveraging a DQM source all
information is provided by the TCR server. There is no requirement to have the JDBC drivers
present on the modeling workstation.
To create a DQM enabled data model, create a new project and ensure “Use Dynamic Query
Mode” is checked.
Figure 5. Dynamic query mode framework manager project
Page 14/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
2. TCR V3 in the Context of Jazz For Service Management
IBM Jazz for Service Management V1.1 is the IBM user interface consolidation platform providing the following services:
•
Administration Services
•
Dashboard Application Services Hub (DASH)
•
Registry Services
•
Reporting Services
•
Security Services
Shared Services
These components are used to consolidate and federate data and user interfaces from IBM
and non-IBM products. Simplified sign-on, capabilities to acquire data from external systems
are key capabilities of IBM Jazz for Service Management. These services can be shared or collocated across servers in large enterprise environments.
Administration
Security
Registry
Services
Content Store
Dashboard
Application &
Reporting Services
Dashboard
Application &
Reporting Services
Dashboard
Application &
Reporting Services
Region 1
Region 2
Region 3
Figure 6. Jazz for Service Management service components
2.1. Administration Services
Administration Services in Jazz for Service Management is an integration service that simplifies the administration of Tivoli products, solutions, or third-party solution in your environment. Through Administration Services, you can manage various aspects of these products
and solutions in your environment, such as health, configuration, availability, life cycle, and
serviceability.
Administration Services has a common and consistent administrative interface that simplifies a wide range of administrative tasks to manage the products and solutions, representing
service management systems.
Administration Services delivers the following capabilities:
Page 15/73
•
Provides visualization of the health of your integrated management environment
•
Reduces the dependencies on highly skilled personnel to administer a heterogeneous
collection of service management products
•
Enables teams to use knowledge from subject matter experts
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
•
Reduces the time to detect, isolate, and resolve problems
•
Improves predictability and repeatability
•
Reduces the time to upgrade existing service management capabilities
•
Improves user experience in the administration of service management products in the
environment
2.2. Dashboard Application Services
Dashboard Application Services Hub provides visualization and dashboard services in Jazz
for Service Management. It has a single console for administering IBM products and related
applications.
Dashboard Application delivers the following capabilities:
•
Provides a Web 2.0 based Systems Management integration platform.
•
Supports proportional dashboard creation that allows users with appropriate permissions to create dashboards by using a self-service palette. They can arrange widgets to
be dynamically displayed in proportion to their size. Multiple widgets can be arranged
on the dashboard in a very flexible and proportional manner.
•
Supports fluid dashboard creation that allows users with appropriate permissions to
create dashboards using a self-service palette. Widgets are dynamically be rearranged
depending on the available screen size. This type of dashboard is suitable for mobile
devices, including tablets and smart phones.
•
Employs a series of intuitive icons to access non-core customization, administration, and
user management tasks, thereby providing more area for displaying user content.
•
Eliminates siloed product consoles that require users to move between separate applications to carry out service management tasks. Users can start from one application to
another within the same dashboard view and drill down into different aspects of their
managed enterprise.
2.3. Registry Services
Registry Services is an integration service that provides a shared data repository for products in an integrated service management environment. Products that discover and manage
shared IT resources can register these IT resources and the services they offer with Registry
Services. Other products can consume data by querying Registry Services for the managed
resources or the associated service providers of interest.
Registry Services provides the following capabilities:
Page 16/73
•
Accommodates different domain-specific schemas.
•
Simplifies resource management tasks. It is built on simple concepts and adds only the
minimum concepts that are required to support various scenarios.
•
Supports different data representations, such as RDF/XML and JSON, being JSON supported as data representation in Provider Registry only.
•
Enables products to provide their own Resource Shape definitions and properties.
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
2.4. Reporting Services
Reporting Services is the Cognos Connection V10.2 component provided through the installation of TCR V3. TCR V3 delivers the Cognos report engine and the self-service reporting front
end to Tivoli products providing historical operational data. To connect to non-Tivoli data
sources is restricted and will require a report developer license.
2.5. Security Services
Security Services in Jazz for Service Management enable the servers of non-WebSphere based
IBM and partners to participate in LTPA based single sign-on with WebSphere servers.
When multiple products and user interfaces are integrated together, the transition from one
UI to another should appear as seamless as possible. One aspect of this integration involves
single sign-on (SSO) functionality, which allows a user to navigate among various products
and user interfaces without being required to enter authentication credentials, such as username and password, more than once.
WebSphere products include SSO functionality based on IBM’s Lightweight Third-Party Authentication (LTPA) technology. When properly configured, this functionality supports navigation among WebSphere-based applications, passing authentication information as LTPA
tokens in HTTP cookies. A user is prompted for authentication credentials only once, and any
subsequent authentications are automatically handled “under the covers” by using the LTPA
tokens included in the associated Web requests.
Authentication Service in Security Services provides user registry and LTPA single SSO integration with non-WebSphere applications. Security Services provide the Authentication Service
that supports issuing and validating LTPA tokens. It is based on the Web Services Trust (WSTrust) specification and is deployed as an application to the WebSphere Application Server on
the Jazz for Service Management server.
Page 17/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
3. Tivoli Common Reporting Component Overview
Tivoli Common Reporting is the Tivoli standard infrastructure for creating, viewing, and managing Tivoli product reports. IBM’s goal is to provide quicker time to value deploying systems
management products and solutions. A large number of Tivoli products provide reports
enabling historical views of availability, utilization, performance and other key metrics. Tivoli
Common Reporting also allows custom reports and Cognos data models to be built and
shared. Tivoli Common Reporting supports both BIRT and Cognos reports. It should however
be mentioned that this paper primarily focuses on the Cognos aspects of Tivoli Common
Reporting.
The Tivoli product provided reports allows to view and share ready-to-use reports and are to
be seen as templates. Should those template reports not meet specific requirement the Cognos Report Studio can be leverage to author additional or modify existing reports. Should the
exposed Cognos data model not meet more advanced reporting requirements, the Cognos
Framework Manager can be used to exposure more of underlying database tables and views.
Figure 7. Working with Cognos
Tivoli Common Reporting consists of data stores, reporting engines, Cognos Connections and
a command-line interface. Tivoli Common Reporting provides a flexible structure that can be
adapted for load balancing and high availability.
Tivoli Common Reporting V3 consists of the following software components:
Page 18/73
•
Jazz for Service Management V1
•
Cognos V10.2
•
WebSphere V8.5
•
DB2 V10.1 hosting the Cognos Content Store
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
3.1. Jazz for Service Management
Jazz for Service Management is the platform providing user interface services for different
IBM solutions and integration capabilities for non-IBM products. Jazz for Service Management
provides a single point for authentication and authorization of multiple web applications. See
“2. TCR V3 in the Context of Jazz For Service Management” on page 15 for more in depth
details. The figure below illustrates TCR and Cognos Connections in the context of Jazz for
Service Management.
Figure 8. Tivoli Common Reporting and Jazz for Service Management
The design objective of Cognos is to provide a powerful tool to expose data in context and make
sense of it. Report consumers and report developers do not necessarily need to understand the
underlying data nor want to have to understand its structure. If you drive a car from A to B you are
not necessarily interested in how the engine is designed and fitted in the car.
Bjoern W. Steffens - 2013
Page 19/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
3.2. Cognos Framework Manager
The Cognos Framework Manager is the tool to manage the component in between the underlying database and Cognos Connections (Cognos Query Studio, Cognos Report Studio etc).
This component is called the Cognos Data Model. There is usually no need to install and use
the Cognos Framework Manager if Tivoli has provided a data model. The Cognos Framework
Manager is used to create and modify Cognos Data Models that consolidate and expose data
to report authors and report consumers. These users typically do not need to or want to know
anything about the database or the structure of it. Providing technical reporting this scenario
most often imply that one person or group manage data models, reports and at the same
time consume the provided material.
1. IBM Jazz for Service Management
2. Cognos Connection
3. Cognos Report Egnine
4. Cognos Data Model
5. Database Server
Analysis Layer
ConsolidationLayer
DatabaseLayer
Cognos Data Model
RDBMS
Figure 9. Cognos data model best practice architecture
•
The database layer in the model is usually referred to as the “Database View”.
•
The consolidation layer in the model is usually referred to as the “Consolidation View”
•
The analysis layer in the model is usually referred to as the “Analysis View” or “Dimensional View”
To develop a Cognos Data Model (the layers) you do need a thorough understanding of the
database structure. Knowledge about SQL is necessary depending on the complexity of the
project.
Page 20/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Figure 10. Cognos Framework Manager ITM V6.3 OS agent data model
3.3. Cognos Administration
Through Cognos Administration the Cognos Server component is managed. The most common activities using the Cognos Administration are:
•
Review historical tasks executed.
•
Review report execution errors.
•
Start, stop schedules and manage priority of current and future jobs.
•
Define and modify Cognos data sources.
•
Import and export report packages.
•
Advanced configuration of the Cognos security system.
•
Accessing the Cognos internal monitoring system.
Figure 11. Cognos Administration
Page 21/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
3.4. Cognos Query Studio
Cognos Query Studio is a tool used to swiftly view and plot data and provides easy to use
visual components to graph data. The focus of Cognos Query Studio is the data exposed from
the underlying database objects through the Cognos Data Model. Cognos Query Studio is
typically used to swiftly look at data before a more advanced report is built using the Cognos
Report Studio. One can look at the Cognos Query Studio as an online database client to look
at the data without the need to have any knowledge about the database tables, database
views, database structure or SQL commands.
Figure 12. Cognos Query Studio
3.5. Cognos Report Studio
The Cognos Report Studio is the tool that provides full visual control of data exposed through
the Cognos Data Model. Cognos Report Studio is the tool to use when reports require more
than one input source, when formatting for printing, saving to disk or mailing becomes more
important. Cognos Report Studio also allows a more advanced manipulation of the data at
the report engine level. The Cognos Report Studio can also be used to override the Cognos
Data Model and send SQL statements directly to the database server. It is not a recommended
practice to regularly override the Cognos Data Model. Once every now and then that could be
required though for good reasons.
Page 22/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Figure 13. Cognos Report Studio
3.6. Cognos Event Studio
Cognos event studio is a data driven tool that can be leveraged to trigger an email or do other
jobs like execute reports. The Cognos event studio has its prime use with sales driven data
where departments or group may need to action certain orders or other data related content.
In the systems management area the reactive part is outside Cognos where events are managed through the incident and problem management process. There are however cases that
could be implemented leveraging Cognos Event Studio. One example could be a report with
unavailable hosts the past 24 hours. If all nodes were online there would be no need to run
and distribute this particular report.
Cognos Event Studio looks at a specified data set and within that data set triggers are defined
what tasks should be executed. Cognos Event Studio can be configured to run tasks based on
new events, changed states, static states or past known errors.
Page 23/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Figure 14. Cognos event studio configuration
Page 24/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
3.7. Cognos Workspace
The target audience for Cognos Workspace is support analysts needing to pull information
together from various reports without depending on the report development group. Cognos
Workspace is proving self-service dashboard creation capabilities.
Being able to bring pieces from many reports together can under many circumstances help in
understanding a problem and also speed up the process with which an incident can be managed.
The control of the objects and filtering are slightly reduced compared to reports. A large
screen would be beneficial but not necessary.
Figure 15. Cognos workspace sample
Page 25/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
3.8. Cognos Workspace Advanced
Cognos Advanced Workspaces provide more freedom of the source choice for the data widgets. Unlike Cognos Workspaces, Cognos Advanced Workspaces provide access to the Cognos
Data Model and a small number of data and display widgets.
The target audience Cognos Workspace Advanced is power consumers who understand the
Cognos Data Model and have a good understanding how to author a report.
Figure 16. Cognos Workspace Advance sample
Running the Cognos Workspace Advanced report provides all the standard features like saving, exporting to Excel, PDF, emailing etc.
Figure 17. Cognos Workspace Advance sample
Page 26/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
3.9. Cognos Active Reports
Cognos Active Reports contain the data they present and are based on MHTML, a web archive
format. Cognos Active Reports also comes with a new set of widgets that can be interconnected. The illustration below connects the drop down list box with the two chart widgets. When
the Hostname changes, the charts are dynamically updated. The advantage is that a report
encapsulating data is that it can be transported outside the TCR system. Existing reports can
be converted and saved as Cognos Active Reports as well also encapsulating the data.
Note: Because Cognos Active Reports contain the data it is not recommended to create such
reports with large number of records for performance reasons. If the Cognos Mobile component has been installed it is essential to consider the potential communication costs that
could be incurred loading Cognos Active Reports on mobile devices.
Figure 18. Active report sample
Page 27/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
4. Deployment Considerations
This section describes the migration routes and high level steps required to complete this
process. It also describes the new architecture where high availability and load balancing
component model has changed. Each installation will have its own intricacies needing careful
consideration before migrated. It is key to perform a thorough assessment of the steps required to migrate an existing installation to V3.
4.1. Migration Routes
Migrating from an older version to the latest TCR V3 release require planning and preparation. Important is the fact that there is no in-place migration and each scenario requires a new
instance of Tivoli Common Reporting V3 as the target. Note that there is no migration support
for TCR V1.1.
1) TCR V1.2/V1.3
Migration Routes
2) TCR V2.1/2.1.1
TCR V3
3) TCR V2.1/2.1.1
with an external
content store
database
Figure 19. Tivoli Common Reporting migration paths
Moving content and settings to the new instance is a manual process with tool support. Common to all three routes though is that the Cognos Server Configuration settings e.g. email
server, user authentication and security restrictions for packages, objects and reports are not
migrated. Detailed migration information and required migration steps are well documented
here . The high level steps for each route is:
1) TCR V1.2/V1.3:
- Install and prepare the target TCR V3 instance.
- Copy BIRT report packages, JDBC drivers, plug-ins and features to the target instance.
- Copy all report package images to the target instance
- Export and import Cognos Report Packages
2) TCR V2.1/V2.1.1:
- Install and prepare the target TCR V3 instance.
- Run the preupgrade.{ bat | sh } script and move the output file to the target instance
- Copy all report package images to the target instance
- Run trcm.{ bat | sh } -upgrade to import content
3) TCR V2.1/V2.1.1 with an external Content Store:
- Run the preupgrade.{ bat | sh } script and move the output file to the target instance
- Copy the source Content Store database to a Target Content Store database
- Install and prepare the target TCR V3 instance and re-use the database copy
- Copy all report package images to the target instance
- Run trcm.{ bat | sh } -upgrade to import content
Page 28/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
4.2. Architecture
Tivoli Common Reporting can be deployed to a single Jazz for Service Management instance
if there are no high availability and load balancing requirements. If there is a high number of
users and high availability is required, Tivoli Common Reporting can be deployed to multiple
instances of Jazz for Service Management. Essential in such a scenario is that the Jazz for Service Management database and the Cognos Content store is shared across all instances.
Report Users
Report Users
HTTP Load Balancer
Jazz for
Service Management
Content Store DB
Jazz for
Service Management
#1
Report
Data
Source
LDAP
Content Store DB
Jazz for
Service Management
#2
Report
Data
Source
Figure 20. Tivoli Common Reporting deployment scenarios
The Jazz for Service Management and Cognos Content Store databases can be on a remote
server in all scenarios. The database server must provide the required service levels in a high
availability and load balanced scenario. The Content Store can also be located on a remote
server and does not have to be local to the TCR server.
Page 29/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
4.3. A Report Development Architecture
If Cognos Data Models are to be developed a full report development environment is required. Developing a Cognos Data Model has similarities with a software development projects and should be planned and staffed accordingly. It is essential to provide Cognos Data
Model developers and report authors with the necessary tools and systems to complete the
development process.
Testing the report with production data is a key milestone during the development process.
This step will provide critical input for tuning a report. Testing reports with a sub set of production data is not a recommended practice. Normally it is simple to point the development
system’s data source connections to the production systems and perform the required tests.
Should this not be possible in a secured and hardened production environment consider
exporting the database or required tables to the development systems.
The illustration below provides an example of how a good practice report development environment architecture. End users and organisations requesting reports must be involved in the
process early having access to the development environment if possible.
Report Consumers
Power Consumers
Report Developers
Report
Development
Systems
Report
Production
Servers
Data Providers
Data Providers
Production
Data
Sources
Development
Data
Sources
Deelopment Environment Production Environment
Figure 21. Report development architecture
Page 30/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
5. Operations
This chapter provides information relevant to operating a reporting solution in an enterprise
environment. The objective is to provide sufficient information about essential aspects getting started and also pointers to more detailed information.
5.1. Disaster and Recovery
Depending on what reporting solutions have been deployed to the TCR servers various types
of backups are required in order to restore a system should one or more components malfunction. A disaster and recovery (DR) concept is governed by the business requirements
around the reporting solution.
The backup concept is governed by the criticality of the reporting solution and must be
designed accordingly. In most cases a reporting solution is not considered critical and can be
down for hours or days before the service need to be back online. There are however cases
where a reporting solution must be available 24 by 7. To architect a continuously available
solution the reporting server(s) must be virtualised with appropriate fail-over mechanisms
provided by the virtualisation software. If physical machines are involved they may need to be
located in different data centres.
There are several aspects to be considered designing a disaster and recovery concept for Tivoli Common Reporting. It is essential to ensure that both of these components can be restored
together or one or the other.
Page 31/73
•
The server running Jazz for Service Management and the Tivoli Common Reporting
application server. This server hosts the web application and potentially a large set of
reports written to disk or archived reports.
•
The Cognos Content Store database. The Cognos Content Store hold information about
all report packages loaded on the server. There may be report output versions in the
Content Store and the configured Cognos object security is stored in here. Schedules
and thresholds for the internal monitoring system
•
The Audit database. If auditing has been enabled that data may need to be backed up
should it be flagged as business critical.
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
5.2. Backup and Restore
In order to be able to restore a broken Tivoli Common Reporting server the following components are required to be backed up:
•
The file system where the IBM installer directory is located. It is key to have a clean
backup of the installer directory as patches and updates are managed through this component. On a Suse Linux installation these directories are located here:
/opt/IBM/IMShared
/opt/IBM/InstallationManager
•
The file system hosting Jazz for Service Management and Tivoli Common Reporting. It is
key to have a backup of these file systems each time one or more files have been modified or tcr_cogconfig.{ bat | sh } has been used to change the configuration. On a Suse
Linux installation these directories are located here:
/opt/IBM/JazzSM
/opt/IBM/WebSphere
•
The database hosting the Cognos Content Store database should be backed up regularly. The Cognos Content Store is the heart of the reporting solution and if this database
is not available Tivoli Common Reporting will not work. Depending on the reporting
solution deployed and the business criticality a more frequent backup may be required.
If possible the Cognos Content Store should be backed up in an OFFLINE status while
Tivoli Common Reporting is not running.
•
The auditing database should be backed up should this feature have been deployed.
The auditing database contain primarily historical performance data about report execution. If service levels are defined against these metrics, this database is required to
be backed up.
•
Each and every report package should be backed up and kept with a version number
when changes are made. This allows a segregated restore of report packages should single components break or if reports, jobs and schedules are accidentally removed. Report
packages are backed up and restored using Cognos Administration.
•
Note: If the TCR server(s) are virtual systems and if space is available it is recommended to
store up-to-date snapshots of these systems permanently.
Page 32/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
5.3. Managing Tivoli Provided Report Packages
The subsequent sections provides information how to import and activate various types of
reports and what the essential steps are to complete this process. Mind that BIRT reports are
managed slightly different compared with the Cognos reports. The data source configuration
for BIRT reports are managed through the trcmd command. Cognos data source configuration is managed through Cognos Administration.
There are install wizards made available for most report packages. These installers may not
always be suitable if firewalls are involved or if an X11 interface is not installed on the server.
Should that be the case, the reports must be installed manually.
One essential aspect concerning database access is that BIRT uses only the JDBC database
drivers. TCR V3 Cognos requires both the full database client on the TCR server and the JDBC
drivers for DQM report packages. Mind that the JDBC drivers are required in a different location though. Depending on the platform TCR is installed on you need to pay attention to the
version of the database client made available to TCR. This is well documented in the User’s
Guide.
5.4. BIRT Report Packages
A Tivoli product provided BIRT report package is delivered as a zip file. These zip files have to
be copied to the JazzSM server and be imported locally using the trcmd command. Copy the
files to the server with the same user as running the TCR server or change ownership accordingly. Not having the correct permissions on the report package zip file when attempting to
import it is one of the more common import issues.
5.4.1 Managing BIRT JDBC Drivers
BIRT report packages leverage the JDBC driver to access the database. All required JDBC drivers need to be copied to the TCR server and then the TCR server must be restarted in order to
pick up those drivers.
The development system used to compile this document had the DB2 JDBC driver (db2jcc.jar
+ db2jcc_license_cu.jar) in the /opt/ibm/db2/V10.1/java directory. These files were copied to
the directory illustrated below. If another vendor database server is implemented, those files
need to be copied to the same directory.
/opt/IBM/JazzSM/reporting/lib/birt-runtime-2_2_2/ReportEngine/plugins/org.eclipse.birt.report.
data.oda.JDBC_2.2.2.r22x_v20071206/drivers
Figure 22. BIRT JDBC driver location.
Page 33/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
5.4.2 Manually Importing Report Packages
Importing a BIRT package provided by a Tivoli product is fairly simple. How can a BIRT report
package be recognized? Unzip the zip file and locate the tcr_metadata directory inside the
directory structure. If that directory can be found it is a BIRT report package that can be imported on the server. The report package below shows the content of the ITM 6.3 BIRT report
package for Performance Analyzer OS Reports.
Figure 23. ITPA OS BIRT report package content.
Note: Sometimes the report package ZIP file contains a readme PDF and another ZIP file. That
second ZIP file contains the BIRT report package to be imported.
Figure 24. BIRT report package import.
Once the report package has been imported with no further parameters, this is the default
location where its ends up at in Cognos Connection.
Figure 25. BIRT report package in Cognos Connection
Page 34/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
5.4.3 Data Source Configuration
The data source configuration is completed using the trcmd command with a number of
parameters. A convenient way to solve this is to script the change by first identifying which
reports need to be changed. The script below illustrates how to automate this required data
source change.
The command to change a report data source for an Oracle database is the same. See comment in the script below for Oracle syntax.
export THE_CMD=/opt/JazzSM/reporting/bin/trcmd.sh
export THE_FILE=./tcr_rpts_to_change
#
# Modify field separator characters
#
SAVEIFS=$IFS
IFS=$(echo -en “\n\b”)
#
# Grep the reports you want to change the data source for
#
$THE_CMD -user jazzadmin -password ***** -list -reports | grep “Performance Analyzer” > $THE_FILE
#
# Change the data source
#
for rpt in `cat $THE_FILE`
do
# DB2 Syntax
$THE_CMD -user jazzadmin -password ***** -modify -datasources -reports -reportname $rpt
-setdatasource odaDriverClass=com.ibm.db2.jcc.DB2Driver -datasource odaURL=”JDBC:db2://tivoli.
bjomain.com:60000/WAREHOUS:currentSchema=ITMUSER;” odaUser=itmuser odaPassword=*****
# Oracle Syntax
#$THE_CMD -user jazzadmin -password ***** -modify -datasources -reports -reportname $rpt
-setdatasource odaDriverClass=oracle.JDBC.driver.OracleDriver odaURL=”JDBC:oracle:thin:@oradb.
bjomain.com:1521:warehous” odaUser=itmuser odaPassword=*****
#done
# restore $IFS
IFS=$SAVEIFS
The figure below illustrates the output of a successful run of the script above. Usually it is only
necessary to change the data source of one report, as they all share the same data source
object in the report package. I do tend to set all of them just to be sure and the script helps
me complete that work while having an interesting discussion about something else with a
customer.
Figure 26. BIRT scripted data source change.
Page 35/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
5.5. Cognos Report Packages
Some Tivoli product provided Cognos reports, like BIRT report packages, are provided as
zip files with an installer wrapped around them. If you want to use the installer to install the
reports, you need to copy it to the TCR server and run the GUI installer. You should make sure
the installer files have the same ownership as the one running the TIP/TCR server. As previously mentioned, it can be a challenge in a hardened production environment to attempt to
run a GUI component.
Cognos report packages can also be installed manually by unpacking the installer media and
just transfer the report package zip file. This is the required approach in a production environment surrounded by firewall and security restrictions.
Cognos report packages leveraging IBM Tivoli Monitoring V6 Data Warehouse data requires a
couple of additional tables providing a virtual star schema. It is a common issue forgetting to
install and populate those additional tables when importing Cognos report packages. How
to install and populate those database objects is documented in the User’s Guide of the Tivoli
product shipping the reports. For IBM Tivoli Monitoring V6.x Operating System Agents it is
essential to complete all steps in that section. New with ITM V6.3 is that maintenance of these
tables can be automated.
http://publib.boulder.ibm.com/infocenter/tivihelp/v61r1/index.jsp?topic=%2Fcom.ibm.itm.
doc_6.3fp2%2Fadminuse%2Ftcr_dimensions.htm
The subsequent sections of this chapter elaborate further on common processes and procedures around Tivoli product provided Cognos report packages.
5.5.1 Managing Data Sources for the TCR/Cognos Server
Before any data sources can be configured for the TCR/Cognos components, it is essential that
the user starting the TCR server has access to the required database client. The script below
is a snippet from the .bashrc file for the nco user starting a TCR development server. With this
configuration the user and TCR/Cognos will be able to access both Oracle and DB2 databases.
This is one of the more common issues, forgetting to configure the database client properly.
Note: For Dynamic Query Mode (DQM) enabled report packages the JDBC files are required. If
only DQM report packages are developed and hosted on the TCR server, the database client is
not required. Mind that the database client is required though for old report packages (Compatible) not supporting DQM.
# Oracle Client for the TCR server
export ORACLE_BASE=/opt/app/oracle
export ORACLE_SID=warehous
export ORACLE_HOME=/opt/app/oracle/product/11.2.0/db_1
PATH=/usr/local/bin:$PATH; export PATH
PATH=$ORACLE_HOME/bin:$PATH; export PATH
LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib; export LD_LIBRARY_PATH
CLASSPATH=$ORACLE_HOME/jlib:$ORACLE_HOME/rdbms/jlib; export CLASSPATH
# DB2 Client for the TCR Server
. /home/db2inst1/sqllib/db2profile
Page 36/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Configuring a data source for TCR/Cognos reports requires a few simple steps and are well
documented in the User’ Guide.
http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/index.jsp?topic=%2Fcom.ibm.psc.
doc_1.1.0.1%2Ftcr_original%2Fttcr_config_db.html
When configuring a TCR/Cognos data source there are steps to test the compatible and JDBC
(DQM) database connection. It is recommended to use those function and verify that a successful message is returned. If this is not the case, common issues are that the database is
either down, not reachable or the database client configuration is incorrect. Note that the
Cognos data source name you need for the ITM V6.X reports should be TDW.
Figure 27. Successful compatible and JDBC(DQM) Cognos data source connection test.
5.5.2 Manually Importing Report Packages
Importing a TCR/Cognos report package provided by a Tivoli product is fairly simple. How do
you recognize if a report package is a BIRT or a Cognos package? Let us assume that we have
managed to download the following file from Passport Advantage (This is the TCR report
package for IBM Tivoli Monitoring V6.3.0.2 OS Agents):
•
ITM_V6.3.0.2_AGT_RPT_MP_ML.tar.gz
The model directory gives us the first indication that this is a report package containing a
Cognos data model and the reports. A BIRT report package does not have this directory.
Figure 28. Tivoli report package content for Cognos reports
Page 37/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
The actual report package including the Cognos data model and the Cognos reports can be
found in the ../reports/cognos_reports/osagents directory. It’s the zip file that need to be copied to the TCR server.
Figure 29. Tivoli report package to be loaded on the TCR server
Copy this zip file to the following directory
> /opt/JazzSM/reporting/cognos/deployment
Figure 30. Tivoli report package location on the TCR server
The remaining steps to import this package are completed by logging on to the TCR server
following these steps.
Cognos Report Packages can also be imported via command line should that be required. For
more information see the trcmd -import command.
Page 38/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Running one of these imported reports you should see output similar to the illustration below.
Figure 31. Cognos report example
Page 39/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
5.6. Scheduling and Distributing Reports to Disk
There are several reasons for scheduling reports and the most prominent ones are to have online copies of reports and to distribute them via email or other media. Important to consider
when emailing reports is the size of a report. Reports usually do not become very large but
there are situations where reports can become larger in size. It may not be wise to overload an
email system with large amounts of reports having considerable size. In such a case a shared
drive or FTP server may be a more suitable option to explore.
Note: The design objective of BIRT & Cognos is not to pump data between systems! If you have the
need to regularly move considerable quantities of data from a Tivoli data source to another tool,
you should consider doing this at the database level and not through BIRT or Cognos!
5.6.1 CLI Report Scheduling
Scheduling reports and writing content to disk can easily be completed by using the trcmd
command in combination with cron on Unix or the built in scheduler on Windows. The advantage is that the IT department managing the TCR Server is in control of what is scheduled, written to disk and how it is further processed. The drawback is that each time a report
user requires a change or needs additional reports scheduled, the IT department has to be
involved. That could add unnecessary overhead to the overall process. This is however not a
concern when most of the reporting is implemented from a technical point of view and the
reports are generally intended for the IT department itself. Where there is a large amount of
report users having various scheduling requirements, managing this through the GUI may be
a more appropriate method.
Once you have decided which reports you want to schedule, you create a script running one
or more of the following statements. Note that the “trcmd -distribute” command applies to
both BIRT and Cognos reports.
> trcmd -user jazzadmin -password ***** -distribute -report “$rpt” -format PDF
-location /tmp/reportname.pdf
Figure 32. Cognos trcmd distribute example
Page 40/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Use the following command to find out which reports you can schedule. Mind that Cognos
reports are typically scheduled through the GUI.
> trcmd -user jazzadmin -password ***** -list -reports
The example in the illustration above uses the default parameter values that have been configured for the report. Should you want to change those in the command you first need to
find out the name of the available parameters. Use the following command to list the details
of a specific report and identify the parameter names:
> trcmd.sh -user jazzadmin -password ***** -list -report “$RPTNAME”
This command should provide output similar to below. Focus on the “Parameters” section in
blue/italic where the required information is provided.
jazztcr:~ # trcmd.sh -user jazzadmin -password ***** -list -report “/content/package[@name=’IBM
Tivoli Monitoring OS Agents Reports’]/folder[@name=’Utilization’]/report[@name=’Disk Utilization
for Single Resource’]”
Report name: /content/package[@name=’IBM Tivoli Monitoring OS Agents Reports’]/folder[@
name=’Utilization’]/report[@name=’Disk Utilization for Single Resource’]
Display name: Disk Utilization for Single Resource
Description: {de=Plattenbelegung für eine einzelne Ressource, zh-tw=單一資源的磁碟使用率, ru=Использование
диска для одного ресурса, ko=단일 자원에 대한 디스크 활용도, en=Disk Utilization for Single Resource, zh-cn=单
一资源的磁盘使用率, it=Utilizzo disco per singola risorsa, fr=Utilisation du disque pour une seule ressource, hu=Egyedi erőforrás lemezhasználata, es=Utilización de disco para un único recurso,
cs=Využití disku pro jednotlivý prostředek, th=การใช้งานดิสก์สำ�หรับรีซอร์สเดี่ยว, ja=単一リソースのディスク使
用率, pt-br=Utilização de Disco para Recurso Único, pl=Wykorzystanie dysku dla jednego zasobu}
Owner: VMMProvider:jazzadmin
Type: Cognos
Parameters:
Name: TCRDateFilter Type: xsdString Capabilities: Default value: Last 30 days Values: [All, Date
range (below), Today, Yesterday, Last 7 days, Last 30 days, Last 90 days, Last 365 days, Current
week, Current month, Current year to date, Last week, Last month, Last year]
Name: TCRDateRange Type: xsdDateTime Capabilities: multivalued boundRange Default value: null
Values:
Name: Summarization Type Type: xsdString Capabilities: Default value: Daily Values: [Hourly,
Daily, Weekly, Monthly, Quarterly, Yearly]
Name: Shift Period Type: xsdInteger Capabilities: Default value: All shifts Values: [All shifts,
Peak hours only, Off peak hours only]
Name: Vacation Period Type: xsdInteger Capabilities: Default value: All days Values: [All days,
Work days, Vacation days]
Name: OS Type Type: xsdString Capabilities: Default value: Linux Values: [Linux, Unix, Windows]
Name: Servers Type: xsdString Capabilities: multivalued Default value: null Values:
Name: Include Remote Filesystems Type: xsdString Capabilities: Default value: No Values: [Yes,
No]
Name: Include Pseudo Filesystems Type: xsdString Capabilities: Default value: No Values: [Yes,
No]
Name: Forecast Type: xsdString Capabilities: Default value: Do not use forecast Values: [Use
forecast, Do not use forecast]
Name: Forecast Period Type: xsdDateTime Capabilities: Default value: null Values:
The parameter section described in blue/italic that can be used as arguments to the trcmd
command. By looking at the “Report Period” we see that when we run it with no parameters,
we get the last 30 days worth of data. Below is the command line example of how to run the
report with “All” as “Report Period” parameter input:
> trcmd.sh -user jazzadmin -password ***** -distribute -report “$RPTNAME” -format PDF -location /tmp/reports/disk_utilisation_server.pdf -parameters “TCRDateFilter=All OS Type=Linux
Servers=tivoli”
If the report parameter format is not specified or documented, enter a dummy value and the
Page 41/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
format of the parameter will be displayed. Each paramter need to be resolved one by one.
> trcmd.sh -user jazzadmin -password ***** -distribute -report “/content/package[@name=’IBM
Tivoli Monitoring OS Agents Reports’]/folder[@name=’Utilization’]/report[@name=’Disk Utilization
for Single Resource’]” -format PDF -location /tmp/reports/disk_utilisation_server.pdf -parameters
“TCRDateFilter=All” “OS Type=Linux” “Servers=tivoli” “TCRDateRange=bla” “Forecast Period=bla”
CTGTRI176E The range parameter TCRDateRange contains a wrong value bla. Valid range format is
“start value,end value”, for example: “dd/MM/yyyy HH:mm:ss a, dd/MM/yyyy HH:mm:ss a”.
trcmd.sh -user jazzadmin -password ***** -distribute -report “/content/package[@name=’IBM >
Tivoli Monitoring OS Agents Reports’]/folder[@name=’Utilization’]/report[@name=’Disk Utilization
for Single Resource’]” -format PDF -location /tmp/reports/disk_utilisation_server.pdf -parameters “TCRDateFilter=All” “OS Type=Linux” “Servers=tivoli” “TCRDateRange=02/12/2013 00:00:00,
02/12/2013 23:59:00” “Forecast Period=bla”
CTGTRI168E The parameter Forecast Period contains a wrong value bla. Valid values are yyyy-MM-dd
HH:mm:ss.SSS.
trcmd.sh -user jazzadmin -password ***** -distribute -report “/content/package[@name=’IBM Tivoli Monitoring OS Agents Reports’]/folder[@name=’Utilization’]/report[@name=’Disk Utilization
for Single Resource’]” -format PDF -location /tmp/reports/disk_utilisation_server.pdf -parameters “TCRDateFilter=All” “OS Type=Linux” “Servers=tivoli” “TCRDateRange=02/12/2013 00:00:00,
02/12/2013 23:59:00” “Forecast Period=2013-12-02 00:00:00”
CTGTRQ088I The report run operation successfully performed.
From here on the report files on disk can be managed using tools available at the operating
system level. Typical actions can be compress, send to ftp server or email if the size is OK.
Page 42/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
5.6.2 GUI Report Scheduling
Scheduling reports through the TCR/Cognos GUI is slightly different compared to working
with and managing reports at the command line. The GUI approach can be more convenient when report users need to be able to schedule reports without the involvement of the IT
department. When Cognos runs a schedule and when “Save” is specified, an output version is
saved to the Cognos Content store. When a scheduling process has been established, the IT
department can focus on ensuring that the TCR server is operating accordingly not having to
assist report users indefinitely. This is where the value becomes more evident leveraging the
GUI scheduling approach.
The GUI scheduling process is completed by assigning TCR/BIRT and TCR/Cognos reports to
a job and then attaching a schedule to that particular job. The steps below outline the work
required in Cognos Connection to complete this:
Page 43/73
•
Create a new job with a descriptive name illustrating what it should accomplish
•
Assign one or more reports to the job
•
Define the parameters, output format and if a report should be refreshed, sent per email
or saved to disk. Specify these parameters for each report attached to the job.
•
Attach a schedule to the job e.g run hourly, daily, weekly, monthly etc.
•
Save the configuration and verify that the job is executed successfully through Cognos
Administration.
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
5.6.3 Configuring Jobs & Schedules
Cognos requires a definition of the “what” and the “when” scheduling activities for execution. The “what” is the Job and the “when” is the schedule when things should execute. The
job defines which report(s) should be included, what format to use (PDF, Excel, HTML etc) if it
should be sent by email or saved and what parameters should be used when the schedule is
executed. Below a sample of a job configuration where a number of reports will be rendered
in sequence.
Figure 33. Cognos job definition example
The schedule defines when the job should be run and for how long. You can of course define
a schedule to run indefinitely or you can specify a specific date when the schedule should
terminate.
Figure 34. Cognos schedule definition example
Page 44/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Once the job and schedule have been configured we need to take a closer look at how to
manage what is actually written to disk. The next section of this chapter will provide some
more in depth information on this topic and provides a hint how you could manage these
process steps.
5.6.4 Saving Reports To Disk
There are two options to available how to write reports to a disk or file system. The first option is where the report can be saved directly to disk when the report is rendered (outside).
The second option is to use the output version saved to the Cognos Content Store (inside)
and write it to disk. A report output version is a snapshot of a report that has been rendered
already and can be viewed without first accessing the source database and re-render the
report.
The difference between the two options is that when saving outside Cognos the filename
on disk can be managed by the user. Saving inside Cognos the output version in the Cognos
Content store is used. The file name is then managed by Cognos and it translates to long serial number. There is a way to recover the file name though. See section “5.6.6 Saving Reports
Inside Cognos” on page 48 for more details.
When TCR/Cognos is installed those features are not enabled. One or the other or both can be
implemented depending on the overall requirements.
Page 45/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
5.6.5 Saving Reports Outside Cognos
Saving a report outside Cognos may seem a little bit odd but what it means is that the Cognos
Content Store is not involved (no output version) and that the report is written directly to disk.
To enable saving to a file system logon to the server where the TCR is installed and execute
the following steps:
•
Logon to the Jazz for Service Management server and run the tcr_cogconfig.sh tool
•
On the menu bar select “Actions” - “Edit Global Configuration”. Select the “General” tab.
•
Specify a value on the server for “Archive Location File System Root”. Mind the syntax of
the entry. It must be prefixed with “file://”.
Figure 35. Cognos Server external location to save reports to
Page 46/73
•
Save the configuration. Important here is that all the check marks display green or the
TCR/Cognos components may not function accordingly. When green check marks are
not provided, it is an indication that the configuration is incorrect.
•
Open an xterm to the Jazz for Service Management server and change ownership of /
opt/reports to the same user starting the server. If this is not the case Cognos will not be
able to create files in this directory.
•
Start a browser and logon to the TCR Server and select “Launch” - “Administration”.
•
Select “Configuration” - “Dispatchers and Services”.
•
Locate the “Define File System Locations” icon on the tool bar. It is the third icon from
the right.
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
•
Create a new file system location and enter a subdirectory name of the root directory
you previously specified. The configuration below illustrates how reports are saved to
/opt/reports
Figure 36. Cognos Administration report save location
Page 47/73
•
Restart the Jazz for Service Management server.
•
Run a report with options. Activate the “Advanced Options” and specify how the file
should be saved.
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Figure 37. Parameters and results end users saving reports to disk
5.6.6 Saving Reports Inside Cognos
Saving a report inside Cognos implies that the Cognos Content Store is involved and that a
report output version is produced before it is written to disk. To enable saving output versions
to a file system, logon to the server where TCR is installed and follow the steps below:
•
Run the tcr_cogconfig.sh tool
•
Select “Data Access” - “Content Manager” and set “True” to “Save report outputs to a file
system?”
Figure 38. Cognos Server save inside configuration
•
Page 48/73
Save the configuration. Important here is that all the check marks display green or the
TCR/Cognos components may not function accordingly. When green check marks are
not provided, it is an indication that the configuration is incorrect.
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Figure 39. Desired Cognos Server save inside configuration save results
•
Logon to the Jazz for Service Management server and launch Cognos Administration.
•
On the “Status” tab, select “System”. At the bottom right-hand corner you will see a Portlet or section called “Setting - System”. Under the double arrow there is an icon displaying “Set properties” when you hover over it with the mouse.
Click the icon and specify the CM.OUTPUTLOCATION and CM.OUTPUTSCRIPT variables.
CM.OUTPUTLOCATION is the file system where the output versions will be written to.
CM.OUTPUTSCRIPT is the script that will run when each report is written to disk. Cognos
will pass the actual report file name written to disk and the file name of the configuration file accompanying the report to that particular script.
Figure 40. CM.OUTPUTLOCATION and CM.OUTPUTSCRIPT configuration
•
Save the configuration and restart the Jazz for Service Management server.
Once this configuration has been completed, reports can be run with options or scheduled
using the GUI and are then written to the file system specified by CM.OUTPUTLOCATION.
Mind to specify “Save” for the report in the job definition. Each time a report is run and the
“Save” option is specified, a report output version is saved to the Cognos Content Store and
then to disk.
It is important to keep an eyes on the size of this directory as a fair amount of reports could
end up here. A good practice would be to leverage IBM Tivoli Monitoring and manage that file
Page 49/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
system. It is not recommended to save output versions to the root file system on Linux/Unix
or the C: drive on Windows.
The final step is to process what TCR/Cognos has written to disk. The CM.OUTPUTSCRIPT
parameter and the script provided can be used to recover the report name accordingly. See
section “5.6.7 Managing Disk Content” on page 50 for further details.
5.6.7 Managing Disk Content
When the save output version to disk configuration has been activated successfully and Jobs
and Schedules are running, you will find something similar to the figure below on the specified file system.
Figure 41. Cognos output versions saved to disk
After some considerable research and pondering on the issue, it became clear that Cognos
has solved a comprehensive issue with this approach as each report saved to disk will have a
unique name regardless of how many concurrent users are running a particular report. This
does however not help at the moment as the objective is to recover the report name defined
in TCR and see that information on disk. From here on things can get complicated depending
on which route you take.
The .xml file accompanied with each report has that detailed information about the report including the name. By parsing and processing that file, it is possible to address this challenge.
Processing that file will only work reliably for jobs and schedules though. File overwriting will
take place if you allow your users to write ad-hoc reports to this directory. That is the reason
why Cognos has selected this unique file naming convention to avoid that particular problem.
The script below illustrates one approach how to recover the actual report name from the
report meta data file (the .xml file).
A shared network drive can be a suitable option permitting users to save reports and allowing them to pick them up there. Use the “save inside Cognos” approach for scheduled reports
needing post processing. The script below provides a sample how the file name could be
recovered on disk.
Page 50/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
#!/usr/bin/sh
# =========================================================================================
# Author :
Bjoern W. Steffens IBM Software Group Services for Tivoli
#
# Version :
2
# Release :
1
# Fix Level :
0
#
# Function :
Renames a Cognos TCR Report file written to disk
#
to the name specified in the Cognos Connection
#
# Dependencies :
CM.outputlocation
#CM.outputscript
#
The Cognos Configuration Variable
#
-> tcr_cogconfig.sh
#-> Environment
#-> Data Access
#-> Save Report outputs ...
#
# Version Control : 05.12.2013
#
# Instructions:
place this script in the CM.outputLocation and
#
assign this script name to the CM.outputscript variable
#
use the full path- and file name
#
# Parameters:
$1: This is the report file to be renamed
#
$2: This file contains the report meta data.
# =========================================================================================
NOW=$(date +”%Y-%m-%d %H:%M:%S”)
LOGFILE=”tcr_outputscript.log”
cd /opt/reports/scheduling
echo “$NOW INFO First Parameter $1, second parameter $2” >> $LOGFILE
# Retrieve the file name
FILE_NAME_ON_DISK=`grep fileName $2 | awk -F ‘>’ ‘{print $2}’ | awk -F ‘<’ ‘{print $0}’ | awk -F
‘.’ ‘{print $1}’`
FILE_EXTENSION=`grep fileName $2 | grep fileName | awk -F ‘>’ ‘{print $2}’ | awk -F ‘<’ ‘{print
$1}’ | awk -F ‘.’ ‘{print $2}’`
# Careful here depending on how many directory levels you have, you need to adap $5 ...
TCR_REPORT_NAME=`grep reportSearchPath $2 | awk -F ‘/’ ‘{print $4}’ | awk -F ‘;’ ‘{print $2}’ |
awk -F ‘&’ ‘{print $1}’`
echo “File Name On Disk: $FILE_NAME_ON_DISK”
echo “File Name Extension: $FILE_EXTENSION”
echo “Report Name: $TCR_REPORT_NAME”
# Dig out all the parameters for the report and add them to the file name
# grep -v AM|PM ignores the second and internal TCR date filter parameter
# Mind that the $IFS lines may need to be adapted depending on how your
# system has been configured. This script required this configuration on
# my Linux development server.
SAVEIFS=$IFS
IFS=$(echo -en “\n\b”)
for i in `grep display $2 | awk -F ‘>’ ‘{print $2}’ | awk -F ‘<’ ‘{print $1}’ | grep -v PM | grep
-v AM`
do
TCR_REPORT_APPENDIX=$i” “$TCR_REPORT_APPENDIX
done
IFS=$SAVEIFS
TCR_REPORT_APPENDIX=`echo “$TCR_REPORT_APPENDIX” | sed ‘s/ *$//’`
#echo “$NOW INFO TCR_REPORT_APPENDIX $TCR_REPORT_APPENDIX” >> $LOGFILE
if [ -n “$TCR_REPORT_APPENDIX” ] ; then
TCR_REPORT_NAME=”$TCR_REPORT_NAME($TCR_REPORT_APPENDIX)”
fi
echo “$NOW INFO Moving file $FILE_NAME_ON_DISK”.”$FILE_EXTENSION to $TCR_REPORT_NAME”.”$FILE_EX-
Page 51/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
TENSION” >> $LOGFILE
mv “$FILE_NAME_ON_DISK.$FILE_EXTENSION” “$TCR_REPORT_NAME.$FILE_EXTENSION”
# Remove the source files if necessary
rm -f “$FILE_NAME_ON_DISK”_desc.xml
Note that this script assumes that you have a flat directory structure for global automation. All
the reports must be in the package directory or the ‘awk’ statements will not work.
“Public Folders > $YOUR_REPORT_PACKAGE > $YOUR_REPORT
Figure 42. Cognos output script folder structure requirements
If there are multiple directories with various depths of folder structures a different script is
required to solve that particular problem. The script merely describes how this problem can
be approached.
Note: The structure of the xml input file has slightly changed from V8 to V10 requiring minor
changes when identifying the file name on disk.
Figure 43. Cognos output script folder with recovered file names.
Page 52/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
5.7. Restricting Access to Cognos Reports
This section provides information how to restrict access to objects within the report package.
The concept of report security is a combination of WMMprovider security and Cognos security. The general idea is to incorporate and leverage WMMprovider security objects inside the
Cognos components. If Jazz for Service Management has been integrated with an LDAP such
as Microsoft Active Directory, those objects can be used as well. Note that only federated
repositories are supported.
TIP/TCR Users
TIP/TCR Groups
with Group Roles
Cognos User &
Group Roles
Cognos Package
& Report Objects
Tivoli Integrated Portal Security System
Cognos Security System
Tivoli Common Reporting Access & Security Configuration Overview
Figure 44. TIP and Cognos security system interaction
This procedure assumes that the following Jazz for Service Management groups exists with
the roles assigned illustrated by the figure below:
•
custom_report_admins
(these TIP roles are required; tcrPortalOperator, iscadmins, chartAdministrator)
•
custom_report_viewers
(these TIP roles are required; tcrPortalOperator)
These groups only need to have login authority and access to the TCR application. All remaining security configuration will be provided inside the Cognos components as described
below.
In order to activate the Cognos security system the Cognos group “Everyone” has to be removed from the Cognos “System Administators” group. Follow the procedure below to make
this required configuration change to the system.
Page 53/73
•
Login with a jazzadmin administrator to the portal
•
Select Reporting – Common Reporting
•
Pull down the Launch menu – Select Administration – Select Security tab
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Page 54/73
•
Select the Cognos Directory and enter a large number in the Entries box and press the
green play button and move to the end of that list so that you can see the “System Administrators” group
•
Open the System Administrators group and select “Set members”. First add the jazzadmin user or the Jazz for Service Management admin group you have configured on your
system. Once the jazzadmin user has been added to this group, remove Everyone. PAY
ATTENTION HERE, IF YOU ADD/REMOVE THE WRONG USERS HERE YOU CAN BLOCK
YOURSELF OUT COMPLETELY.
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Page 55/73
•
Exit the Administration configuration and go back to the Cognos Connection and select
Your package. In our example we are using the report package “Sample Report Package
with Security”. The next steps will provide read-only access to the “Operations Reports”
for custom_report_viewers and remove access to the remaining objects.
•
Click the “more...” button on the tool bar (the one to the right of the red X in the upper
right hand corner). Select the permissions tab and scroll to the bottom and press the
“add...” link. Click on the vmmprovider so that you can see the content of that object.
Push both custom_tcr_viewers and custom_tcr_admin across to the right side and press
the “OK” button.
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
•
Page 56/73
Put a check mark in front of the custom_tcr_viewers group and grant read and execute.
Remove the check mark for custom_tcr_viewers and set it in front of custom_tcr_admins and grant all rights. Press the “OK” button when finished.
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
•
Page 57/73
Configure the following access policies for the report package. This will grant read-only
access to all objects including sub folders etc. For any objects inside this package that
should not be visible to custom_report_viewers, deny access or leave empty.
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
•
Eventually when all the necessary access properties have been set, a report package
with restricted access can look as follows
­
Page 58/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
5.8. Recommended Report Development Practice
It is recommended to segregate Cognos data modeling and report development for several
reasons. One of them is that Cognos data model development can include changes to the
underlying database and changes to Jazz for Service Management user configuration. These
changes must be kept transparent to report users. Another reasons is that report users do not
necessarily have the required insight about the database structure and complexity that needs
to be hidden in the Cognos Data Model.
Cognos Data Models and Cognos reports should be adequately tested and tried in a development environment and preferably be accepted by the end user community prior to production rollout. The figure below illustrates a suggested Cognos data model and report development process providing segregation of duties. The subsequent chapters of this document will
elaborate and clarify these topics further.
Report Users
1
Data model development using
the Cognos Framework Manager
2
Report development using
the Cognos Report Studio.
3
Report power users test and
approve new reports and changes.
4
A Tivoli Systems Administrator
exports report packages.
A Tivoli Systems Administrator
manage access to reports and
packages leveraging an LDAP.
Automated reports distribution
is adressed in this step as well.
5
3
Process steps
Component and user connections
Production Environment
Development Environment
Jazz V3.x Server
PROD Server
Jazz V3.x Server
DEV Server
4
2
LDAP
3
5
1
Tivoli Systems
Administrator
PROD Database(s)
Report Developers
DEV Database(s)
Figure 45. Recommended report development process
A very important aspect during report development and user acceptance testing is performance. It is essential that the reports are tested with a considerable amount of data. If a report
takes more than around 15 seconds to render acceptance issues are to be expected. Should
that be the case the report need to be looked closer at to identify potential optimizations.
Looking closer at the report SQL code may also be necessary including database tuning e.g.
adding indexes. Mind that adding indexes will slow down all write processes to that specific
table. Creating a database view handing off more work to the database server is also an option.
Page 59/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
5.9. Cognos Report Templates
Creating report templates has several advantages and is mostly deployed to get a common
look and feel across reports. Essential aspects are where data is placed, where parameters are
presented and adding company logos and images to reports. Data containers, database objects and queries are typically not placed in templates. A template should only provide layout
components and possibly code and functions common across reports.
There are three ways to approach the topic of templates:
•
A report can simply be created and saved in a folder with a name indicating it is a
template. This is a very quick and easy method but with the disadvantage the template
is stored in a folder. Such a template is also not system wide and may not be accessible
to everyone. A copied report always has a Cognos Data Model attached to it. Using such
a template it is important to remember to change to the correct Cognos Data Model
and save the report with a new name or the template will be changed and potentially
broken when saved.
•
A layout component library is one or more reports from which objects are referenced.
When authoring reports layout components are inserted referencing the source report.
The advantage with this approach is that when the source report is changed, all reports
referencing the changed layout components are updated accordingly.
Figure 46. Re-using layout components
•
A template can be added to the “new report” dialogue. This template is then available
system wide and can be accessed by everyone with the authority to author and save
new reports. This approach involves editing three xml files on the TCR server. A system
wide template does not have a Cognos Data Model attached by default. Attaching a
Cognos Data Model is part of the first steps using such a template. A system wide template can not be changed or overwritten by a user. The remain part of this chapter will
deep dive on that topic.
It is recommended to start with a report and focus on common layout components and reference that particular report. The source report should be secured and backed up accordingly
to avoid accidental changes as it may affect a larger number of reports. A layout library can be
a more suitable option versus system wide templates depending on the overall requirements.
Once template changes stabilize its a good point in time to consider creating a system wide
template. The disadvantage with system wide templates is that server access is required to
modify them.
Page 60/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Before starting to create templates and layout component libraries images and logos need to
be placed on the TCR server first. The paths below indicates where these are to be copied to
on a Suse Linux system. The path to a Windows system is similar. A restart of the server may be
necessary to be able to access the images.
/opt/IBM/JazzSM/reporting/cognos/webcontent/tivoli/tcr_common/images
/opt/IBM/JazzSM/profile/installedApps/JazzSMNode01Cell/IBM Cognos.ear/p2pd.war/tivoli/tcr_common/
images
The images ( or company logos ) has the following URL property:
../tivoli/tcr_common/images/$image_logo_name
5.10.Creating a System Wide Report Templates
This process involves editing the resources.xml, templates.xml and reportstudio_en.xml files.
The process can seem cumbersome and one can feel slightly overwhelmed when opening
the first two files. Once these files have been edited correctly this or these new templates will
bring added value to the installation.
Before you begin, copy resources.xml, templates.xml and reportstudio_en.xml from this location on the TCR server to a workstation with an XML editor. If your installation is German you
may need to edit reportstudio_de.xml too. If your install supports other languages you may
need to edit all required reportstudio_{ language code}.xml files.
./JazzSM/profile/installedApps/JazzSMNode01Cell/IBM Cognos.ear/p2pd.war/pat/res/
•
Create your template with the layout components and company logos and images
•
Add your new and edited template xml code to templates.xml
•
Provide an icon for the template
•
Ammend the resources.xml file
•
This is an optional edit but may need to be applied. Edit reportstudio_en.xml and all
other language specific files required in your environment
Locate this section in the file and add the “string id” element. Make sure the template
name and label match what has been inserted into the resources.xml and templates.xml
files.
<section name=”RSB” type=”UI”>
.
.
<string id=”myReport-Template” type=”Control Label”>myReport-Template</string>
•
Secure the orignal resources.xml, templates.xml and reportstudio_{language code}.xml
files in these directories on the server.
./JazzSM/profile/installedApps/JazzSMNode01Cell/IBM Cognos.ear/p2pd.war/pat/res/
./JazzSM/reporting/cognos/webcontent/pat/res
•
Copy the edited files to these directories on the server.
./JazzSM/profile/installedApps/JazzSMNode01Cell/IBM Cognos.ear/p2pd.war/pat/res/
Page 61/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
./JazzSM/reporting/cognos/webcontent/pat/res
•
Close the Report Studio and empty the Internet Explorer cache. If Firefox is used that
cache need to be cleared too.
Figure 47. Clearing the Internet Explorer cache
5.11.Identifying System Bottlenecks
This section provides some basic information how to start with investigating potential bottlenecks and performance tuning.
The first symptom or indication of a performance issue is usually users observing poor report performance and calling the help desk. There are a number of ways to preempt this that
should be considered at system design time. One of the most important measures against
poor performing reports is to test them during design time with ample data quantities. These
tests do however not address the scenario with a report’s rendering performance degrade
over time.
5.11.1Turning on Cognos Auditing
Cognos provides its own auditing system with a variety of metric values written to an external
database. Of particular interest is the report performance metrics where each report’s execution time is stored. This information provides an indication of reports that could be looked
closer at. There will always be reports having long execution times but this type of auditing
provides a forward looking monitoring strategy where an IT department can react before the
Help Desk deposits the topic.
Page 62/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Please read the Cognos online document for more information about auditing
The audit database requires a specific structure and the Cognos documentation recommends
to use the script creating the Cognos Content Store to create the audit database. The script
can be found on the the TCR V3 installation media.
> TCR_generate_content_store_db2_definition. { bat | sh }
Run tcr_cogconfig. { bat | sh } on the TCR server and specify the new and additional log source
(do not remove the existing log file source).
•
Right-click Logging
•
Select New Resource - Destination
•
Provide a name and make sure it is a database
•
Right-click that newly created destination
•
Select New Resource - Database
•
Specify the connection details and credentials for that database.
•
Right-click this new object and select test. This test has to be successful. If there is an
error message provided it is likely that the JDBC drivers have not been copied to the
right location. See “6.2. New Observations” on page 71 where the JDBC files must be
present.
•
Restart the TCR Server
Figure 48. Cognos database log source
Connect to the newly created auditing database and verify that COGIPF_* tables have been
created and that TSN_* table spaces are present. Should the database for some reason still be
empty troubleshooting is required. The cogserver.log file provide indication should there be a
problem with connecting to the database creating the tables. During startup of the TCR server
grep for “LogService” and look for suspicious log entries.
Page 63/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Figure 49. Cognos audit database
Once the infrastructure for auditing has been prepared, auditing needs to be enabled using Cognos Administration. As already mentioned Cognos provides this system and it simply
has to be enabled. Auditing can be enabled for the entire system or for specific components.
When a components logging level is set to minimal the auditing system is turned off. Basic
logging turns auditing on. Any other level above basic should only be turned on for troubleshooting purposes.
Mind that turning on a wide variety of auditing metrics will have an impact on system performance. The metrics used for this document; Batch Report Server and Report Service did not
seem to have a noticeable impact on the system. It is recommended to include auditing of
these services as part of the system architecture as it provides vitial information about report
execution allowing forward looking report performance monitoring.
Login to Tivoli Common Reporting with a user with administrator authority (jazzadmin) and
start Cognos Administration.
•
On the status tab select System
•
Click the system name in the Scorecard section
Figure 50. Audit tree selection
•
Page 64/73
Keep clicking the system name till all the services appears
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Figure 51. Audit target object
•
Select BatchReportService
•
Change the settings for the logging level from minimal to basics.
Figure 52. Audit object logging level
•
Repeat this for ReportService which can be found further down in the list.
•
Return to Cognos Connection and run a few reports.
•
Connect to the database and observe the content of the COGIPF_RUNREPORT table. The
COGIPF_RUNTIME column provides the report run time in milliseconds.
Figure 53. Cognos report auditing data
Page 65/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
A Tivoli Monitoring Agent Builder can be leveraged to monitor this table in real time and TCR
reports can be written for historical analytics of report usage and performance.
Figure 54. Audit report sample - hourly average report execution time
5.11.2Cognos Monitoring
Cognos Provides its own and internal monitoring system where thresholds can be set and
observed. It can be accesses and configured via Cognos Administration. For more information
see Cognos online documentation. Part of this section has been copied from the Redbook
sg247912 - IBM Cognos Business Intelligence V10.1 Handbook).
Page 66/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Figure 55. Cognos internal monitoring system
The Cognos server provides a JMX interface where these metrics can be accessed externally.
Metrics of particular interest are:
Page 67/73
•
AverageTimeInQueue
•
FailedRequestPercent and SuccessfulRequestPercent
•
MillisecondsPerSuccessfulRequest
•
NumberOfFailedRequests
•
NumberOfProcessedRequests
•
NumberOfRequests
•
NumberOfSessions
•
NumberOfSessionsHighWaterMark
•
NumberOfSuccessfulRequests
•
QueueLengthHighWaterMark
•
ResponseTimeHighWaterMark
•
ServiceTimeAllRequests
•
ServiceTimeFailedRequests
•
SuccessfulRequestsPerMinute TimeInQueue
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
•
TimeInQueue
•
TimeInQueueHighWaterMark
The individual metrics are divided into three main metric groups:
•
Request. These metrics pertain to the specific requests that are handled by each component in the environment. Notable metrics that are included in this group are:
– Amount of processed requests
– The percentages of successful versus failed requests
– The amount of processing time for these requests
•
Queue. These metrics provide insight into the amount of requests that are not handled
immediately and therefore are placed into a queue to be processed when the resources
become available. Several metrics in this group are the amount of requests that have
been in the queue, the length of the queue, and how much time requests have spent in
the queue.
•
Process. These metrics display information regarding the amount of processes required
by the product to function. Metrics such as the number of current processes and the
maximum number of processes that were spawned are available.
There are a few metrics located outside of the three main metric groups (JVM uptime and
heap size information, for example), but the majority of the individual metrics are a part of the
three metric groups.
Performance, capacity
and health analytics
TCR/Cognos JMX Monitoring
WAS Monitoring
OS Monitoring
Tivoli Data Warehouse
DB Monitoring
Enterprise Event Management
IBM Tivoli Monitoring
Figure 56. TCR/Cognos monitoring concept
Page 68/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Monitoring Cognos using an enterprise tool the following aspects should be considered:
•
Paging
•
CPU Utilisation
•
Memory Utilisation
•
Disk Space
•
Monitoring cogserver.log for errors and suspicious behaviour.
•
Monitor the COGIP_RUNREPORT audit table for reports with excessive run-times.
•
If possible WebSphere should be monitored leveraging an enterprise tool.
Figure 57. WebSphere application server summary
Figure 58. WebSphere application health
Page 69/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
6. Common Issues
6.1. Less Recent Observations Still Applicable
There are a couple of prominent issues with most installations where customers are struggling with configuring a TCR/Cognos environment. These issues are simple to resolve but
could be difficult to spot at first sight.
•
The required database client is not installed properly and/or the user starting the TCR
server on a Linux/Unix platform does not have access to the database client. Resolving
this issue is simple. On Windows you install the required client and restart the TCR server.
On Linux/Unix you install the required database client and set the necessary environment variables accordingly and restart the TCR server.
•
The Cognos Data Source has not been configure in the Cognos Administration. If the database client has been installed accordingly, the Cognos Data source has to be defined
and tested through Cognos Administration. Adding data sources to Cognos Administration does not require the TCR server to be restarted.
•
The required historical Tivoli Data Warehouse data has not been collected accordingly.
Usually the Tivoli product Users Guide elaborates adequately how to enable this. Use
the Tivoli Monitoring Version 6 historical collection configuration tool to complete this
configuration.
•
The IBM_TRAM tables and stored procedures have not been created for IBM Tivoli
Monitoring Version 6 or ITCAM reports. The IBM Tivoli Monitoring Administration Guide
elaborates on this thoroughly.
•
For windows 2008 installation, make sure the machine is running Windows ‘Event Log’
service (verify from Control Panel -> Administrative Tools -> Services) before starting TCR
installation. If this service is not running, then please start it else installation will fail in
the step of Cognos installation
•
Pointing the Cognos Framework Manager to a different TCR Server causing encryption
key creation errors.
On the Cognos Framework Manager workstation, close the Cognos Framework Manager, rename the following directories
..\csk
..\encryptkeypair
..\signkeypair
Start Cognos Configuration on the workstation and save the configuration with the
pointers to the new server. This will create the SSH keys for the new TCR Server.
Page 70/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
6.2. New Observations
•
Attempting to Install Jazz for Service Management V1.1 on Linux with FireFox 17.0.3 the
launchpad does not start properly. The changes below are also mentioned in this Technote.
Open the <launchpad_root_dir>/launchpad/preferences.sh file, and edit it to add the
following line to the file (this line can be added anywhere in this file, ensure there is no
\n after the line if pasted at the end of the file):
echo ‘user_pref(“security.enablePrivilege.enable_for_tests”, true);’ >>$userprefpath/user.
js
Restart the launchpad
•
The following error message is displayed when running reports:
DPR-ERR-2056 The Report Server is not responding
There are several possibilities causing this problem.
1) This Technote describes how to remove Windows .ttf files from /opt/IBM/JazzSM/reporting/cognos/bin/fonts
2) The value of ulimit -n is too low. Increase that value
3) There are *.rtm files in the ../cognos/data/cqe/RTModels directory. Manually delete
the *.rtm files in the cognos/data/cqe/RTModels directory.
4) The required JDBC files for Content Store, Dynamic Query Mode and BIRT reports
have not been copied to the appropriate locations. On a Suse Linux System the db2jcc.
jar and db2jcc_license_cu.jar files are expected in these directories
/opt/IBM/JazzSM/reporting/cognos/webapps/p2pd/WEB-INF/lib/db2jcc_license_cu.jar
/opt/IBM/JazzSM/reporting/lib/birt-runtime-2_2_2/ReportEngine/plugins/org.eclipse.birt.report.data.oda.JDBC_2.2.2.r22x_v20071206/drivers/db2jcc_license_cu.jar
/opt/IBM/JazzSM/profile/installedApps/JazzSMNode01Cell/IBM Cognos.ear/p2pd.war/WEB-INF/lib/
db2jcc_license_cu.jar
/opt/IBM/JazzSM/lib/db2/db2jcc_license_cu.jar
Restart the server and run the report again causing the error.
•
If the ITM V6.3 Agent reports are installed manually the image files from the report
package need to be copied to these directories on the server:
./JazzSM/reporting/cognos/webcontent/tivoli/ITM/images
./JazzSM/profile/installedApps/JazzSMNode01Cell/IBM Cognos.ear/p2pd.war/tivoli/ITM/images
•
Page 71/73
Having created the Cognos Auditing database manually and restarted the TCR server,
the Auditing database remains empty.
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
Use the TCR_generate_content_store_db2_definition.{ bat | sh } script to create the
auditing database.
Page 72/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47
A Field Guide to Tivoli Common Reporting V3
7. References
Jazz for Service Management Information Center
Product Documentation
Tivoli Common Reporting @ DeveloperWorks
TCR Community
Tivoli Common Reporting Recommended Practices
Download PDF Document
Tivoli Common Reporting Forum
TCR Forum
Tivoli Common Reporting on YouTube
http://www.youtube.com/results?search_query=tivoli+common+reporting+V3&sm=3
Cognos V10.2 Online Documentation
Product Documentation
Cognos V10.2 PDF Documentation
Product Documentation
Cognos Recommended Practices
DeveloperWorks
IBM Cognos Business Intelligence V10
ISBN-13 978-0-13-272472-2
ISBN-10 0-13-272472-2
Page 73/73
IBM Switzerland Ltd.
Last Modified: 29.01.2014 17.47