Professional Documents
Culture Documents
to
Tivoli Common Reporting V3
Bjoern W. Steffens
IBM Certified Consulting IT Specialist
&
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.
General clarifications and expanding
v01r02 20.03.2012 Bjoern W. Steffens
on how to save reports to disk.
Adapting the document for Tivoli
v03r01 01.29.2014 Bjoern W. Steffens Common Reporting V3 and expand-
ing 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
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
5.1. Disaster and Recovery 31
5.2. Backup and Restore 32
Table of Figures
Figure 1. TCR V3 high availability and load balanced architecture 9
Figure 2. IBM Cognos app on an iOS Tablet 12
Figure 3. JAR files required for dynamic query mode on a Suse 11 Linux server 13
Figure 4. JDBC data source connection test 14
Figure 5. Dynamic query mode framework manager project 14
Figure 6. Jazz for Service Management service components 15
Figure 7. Working with Cognos 18
Figure 8. Tivoli Common Reporting and Jazz for Service Management 19
Figure 9. Cognos data model best practice architecture 20
Figure 10. Cognos Framework Manager ITM V6.3 OS agent data model 21
Figure 11. Cognos Administration 21
Figure 12. Cognos Query Studio 22
Figure 13. Cognos Report Studio 23
Figure 14. Cognos event studio configuration 24
Figure 15. Cognos workspace sample 25
Figure 16. Cognos Workspace Advance sample 26
Figure 17. Cognos Workspace Advance sample 26
Figure 18. Active report sample 27
Figure 19. Tivoli Common Reporting migration paths 28
Figure 20. Tivoli Common Reporting deployment scenarios 29
Figure 21. Report development architecture 30
Figure 22. BIRT JDBC driver location. 33
Figure 23. ITPA OS BIRT report package content. 34
Figure 24. BIRT report package import. 34
Figure 25. BIRT report package in Cognos Connection 34
Figure 26. BIRT scripted data source change. 35
Figure 27. Successful compatible and JDBC(DQM) Cognos data source connection test. 37
Figure 28. Tivoli report package content for Cognos reports 37
Figure 29. Tivoli report package to be loaded on the TCR server 38
Figure 30. Tivoli report package location on the TCR server 38
Figure 31. Cognos report example 39
Figure 32. Cognos trcmd distribute example 40
Figure 33. Cognos job definition example 44
Figure 34. Cognos schedule definition example 44
Figure 35. Cognos Server external location to save reports to 46
Figure 36. Cognos Administration report save location 47
Figure 37. Parameters and results end users saving reports to disk 48
Figure 38. Cognos Server save inside configuration 48
Figure 39. Desired Cognos Server save inside configuration save results 49
Figure 40. CM.OUTPUTLOCATION and CM.OUTPUTSCRIPT configuration 49
Figure 41. Cognos output versions saved to disk 50
Figure 42. Cognos output script folder structure requirements 52
Figure 43. Cognos output script folder with recovered file names. 52
Figure 44. TIP and Cognos security system interaction 53
Figure 45. Recommended report development process 59
Figure 46. Re-using layout components 60
Figure 47. Clearing the Internet Explorer cache 62
Figure 48. Cognos database log source 63
Figure 49. Cognos audit database 64
Figure 50. Audit tree selection 64
Figure 51. Audit target object 65
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 solu-
tion 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 pro-
vide 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 particu-
lar report further.
It is the objective of this paper to provide a comprehensive overview how to manage the vari-
ous 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 com-
ponents 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 installa-
tion with a DB2 database server has been used to provide the examples in this document.
• 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
Report
Data
Source
/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.
• Run the installMobile.sh and install the mobile components. The installMobile.{ bat | sh }
is located in the actual product installation path.
• Start a browser on your mobile device and navigate check that the mobile interface is
running
http://jazzserver:16310/tarf/m/index.html
• Download the IBM Cognos app from the Apple App Store and connect it to the IBM Jazz
for Service Management Server
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 in-
volve 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-de-
signed.
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
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.
To create a DQM enabled data model, create a new project and ensure “Use Dynamic Query
Mode” is checked.
Shared Services
Administration
Security
Registry
Services
Content Store
Administration Services has a common and consistent administrative interface that simpli-
fies a wide range of administrative tasks to manage the products and solutions, representing
service management systems.
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 user-
name and password, more than once.
WebSphere products include SSO functionality based on IBM’s Lightweight Third-Party Au-
thentication (LTPA) technology. When properly configured, this functionality supports navi-
gation 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 integra-
tion 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 (WS-
Trust) specification and is deployed as an application to the WebSphere Application Server on
the Jazz for Service Management server.
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 Cog-
nos 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.
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.
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.
Analysis Layer
ConsolidationLayer
DatabaseLayer
RDBMS
• 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 “Dimen-
sional 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.
Figure 10. Cognos Framework Manager ITM V6.3 OS agent data model
In the systems management area the reactive part is outside Cognos where events are man-
aged 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.
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 man-
aged.
The control of the objects and filtering are slightly reduced compared to reports. A large
screen would be beneficial but not necessary.
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.
Running the Cognos Workspace Advanced report provides all the standard features like sav-
ing, exporting to Excel, PDF, emailing etc.
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 com-
ponent has been installed it is essential to consider the potential communication costs that
could be incurred loading Cognos Active Reports on mobile devices.
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 re-
quired to migrate an existing installation to V3.
3) TCR V2.1/2.1.1
with an external
content store
database
Moving content and settings to the new instance is a manual process with tool support. Com-
mon 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
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 Ser-
vice Management database and the Cognos Content store is shared across all instances.
Jazz for
Service Management
Content Store DB
Jazz for Jazz for
Service Management Service Management
#1 #2
LDAP
Content Store DB
Report
Report
Data Data
Source Source
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.
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 pro-
duction 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 envi-
ronment architecture. End users and organisations requesting reports must be involved in the
process early having access to the development environment if possible.
Report Report
Development Production
Systems Servers
Data Providers
Data Providers
Development Production
Data Data
Sources Sources
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 get-
ting started and also pointers to more detailed information.
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 Tivo-
li Common Reporting. It is essential to ensure that both of these components can be restored
together or one or the other.
• 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.
/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 modi-
fied 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 regu-
larly. 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 ex-
ecution. 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 sin-
gle 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.
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 loca-
tion 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.
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
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.
Once the report package has been imported with no further parameters, this is the default
location where its ends up at in Cognos Connection.
The command to change a report data source for an Oracle database is the same. See com-
ment 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.
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 environ-
ment 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 proce-
dures around Tivoli product provided Cognos report packages.
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 (Com-
patible) not supporting DQM.
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 suc-
cessful 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.
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 cop-
ied to the TCR server.
> /opt/JazzSM/reporting/cognos/deployment
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.
Running one of these imported reports you should see output similar to the illustration be-
low.
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!
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
Use the following command to find out which reports you can schedule. Mind that Cognos
reports are typically scheduled through the GUI.
The example in the illustration above uses the default parameter values that have been con-
figured 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.
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 -loca-
tion /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
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”.
CTGTRI168E The parameter Forecast Period contains a wrong value bla. Valid values are yyyy-MM-dd
HH:mm:ss.SSS.
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.
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:
• 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.
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.
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.
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 se-
rial 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.
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://”.
• 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.
• 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 37. Parameters and results end users saving reports to disk
• 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.
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 Port-
let or section called “Setting - System”. Under the double arrow there is an icon display-
ing “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 configura-
tion file accompanying the report to that particular script.
• 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
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.
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 in-
cluding 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 allow-
ing 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.
cd /opt/reports/scheduling
echo “$NOW INFO First Parameter $1, second parameter $2” >> $LOGFILE
# 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}’`
# 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
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.
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.
Cognos Package
& Report Objects
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 re-
maining 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 re-
moved from the Cognos “System Administators” group. Follow the procedure below to make
this required configuration change to the system.
• Login with a jazzadmin administrator to the portal
• Select Reporting – Common Reporting
• Pull down the Launch menu – Select Administration – Select Security tab
• 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 Ad-
ministrators” group
• Open the System Administrators group and select “Set members”. First add the jazzad-
min 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.
• 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.
• 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_ad-
mins and grant all rights. Press the “OK” button when finished.
• 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.
• Eventually when all the necessary access properties have been set, a report package
with restricted access can look as follows
Cognos Data Models and Cognos reports should be adequately tested and tried in a develop-
ment environment and preferably be accepted by the end user community prior to produc-
tion rollout. The figure below illustrates a suggested Cognos data model and report develop-
ment process providing segregation of duties. The subsequent chapters of this document will
elaborate and clarify these topics further.
Data model development using
1
Report Users the Cognos Framework Manager
Report development using
2
the Cognos Report Studio.
Report power users test and
3
approve new reports and changes.
A Tivoli Systems Administrator
4
exports report packages.
A Tivoli Systems Administrator
5
manage access to reports and
packages leveraging an LDAP.
3 Automated reports distribution
is adressed in this step as well.
Process steps
Component and user connections
Production Environment Development Environment
4
LDAP 2
3
5
1 Report Developers
A very important aspect during report development and user acceptance testing is perfor-
mance. 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 op-
tion.
• 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 tem-
plate 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 refer-
ence 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.
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
../tivoli/tcr_common/images/$image_logo_name
Before you begin, copy resources.xml, templates.xml and reportstudio_en.xml from this loca-
tion 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>
./JazzSM/profile/installedApps/JazzSMNode01Cell/IBM Cognos.ear/p2pd.war/pat/res/
./JazzSM/reporting/cognos/webcontent/pat/res
./JazzSM/profile/installedApps/JazzSMNode01Cell/IBM Cognos.ear/p2pd.war/pat/res/
• Close the Report Studio and empty the Internet Explorer cache. If Firefox is used that
cache need to be cleared too.
The first symptom or indication of a performance issue is usually users observing poor re-
port 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.
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
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.
Once the infrastructure for auditing has been prepared, auditing needs to be enabled us-
ing 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 trouble-
shooting purposes.
Mind that turning on a wide variety of auditing metrics will have an impact on system perfor-
mance. 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
• Keep clicking the system name till all the services appears
• Select BatchReportService
• Change the settings for the logging level from minimal to basics.
• 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.
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
The Cognos server provides a JMX interface where these metrics can be accessed externally.
Metrics of particular interest are:
• AverageTimeInQueue
• FailedRequestPercent and SuccessfulRequestPercent
• MillisecondsPerSuccessfulRequest
• NumberOfFailedRequests
• NumberOfProcessedRequests
• NumberOfRequests
• NumberOfSessions
• NumberOfSessionsHighWaterMark
• NumberOfSuccessfulRequests
• QueueLengthHighWaterMark
• ResponseTimeHighWaterMark
• ServiceTimeAllRequests
• ServiceTimeFailedRequests
• SuccessfulRequestsPerMinute TimeInQueue
• 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 com-
ponent in the environment. Notable metrics that are included in this group are:
Performance, capacity
and health analytics
WAS Monitoring
OS Monitoring
DB Monitoring
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.
6. Common Issues
6.1. Less Recent Observations Still Applicable
There are a couple of prominent issues with most installations where customers are strug-
gling 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 environ-
ment variables accordingly and restart the TCR server.
• The Cognos Data Source has not been configure in the Cognos Administration. If the da-
tabase client has been installed accordingly, the Cognos Data source has to be defined
and tested through Cognos Administration. Adding data sources to Cognos Administra-
tion 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 Man-
ager, 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.
1) This Technote describes how to remove Windows .ttf files from /opt/IBM/JazzSM/re-
porting/cognos/bin/fonts
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.re-
port.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
• Having created the Cognos Auditing database manually and restarted the TCR server,
the Auditing database remains empty.
7. References
Jazz for Service Management Information Center
Product Documentation
TCR Community
TCR Forum
http://www.youtube.com/results?search_query=tivoli+common+reporting+V3&sm=3
Product Documentation
Product Documentation
DeveloperWorks
ISBN-13 978-0-13-272472-2
ISBN-10 0-13-272472-2