An introduction to TWS 8.6 command line reporting

by Pete Meechan

One of the new features provided by TWS 8.6 is the command line reporting capability, also referred to as reportCLI. The command line reporting capability is a standalone command line interface that uses the Business Intelligence and Reporting Tools or BIRT open source product to produce reports.

The capability is supplied as a separately available download in Passport Advantage and can be installed on any supported system – it does not require any TWS components for execution. Download the tar or zip file for your required OS platform, decompress the downloaded file into your chosen location and the software is executed from that location – there is no “installation” program required.

Customising the reporting setup

Before you can use the command line reporting you need to perform some basic customisation in the <package_location>/config/common.properties file. The sample shown below shows the file contents (without the supporting comments explaining each of the parameter settings) after customisation for my test system.

The ContextRootUrl setting is used to identify the location where the report is available to a HTTP server.

The optional mail.xxxx parameters provide for sending a zipped copy of the report via e-mail to the indicated addresses upon completion of the report generation.

Note that the PARAM_Password field is encrypted following the first execution of the command line reporting script.

 

Customising the report options

The command line reporting supplies a number of predefined reports, each with a corresponding properties file that contains options for the report. The properties files can be found in the <package_location>/reports/templates directory. The table below summarises the supplied reports and their associated properties file.

Properties file	Description
ad.properties	Audit detail report – requires AuditStore global option (as) to be set to DB (Database) or both
ag.properties	Audit general summary report – requires AuditStore global option (as) to be set to DB (Database) or both
jrh.properties	Job Run History report
jrs.properties	Job Run Statistics report
sql.properties	Custom SQL report
wwr.properties	Workstation Workload Runtime report providing detailed job executions by workstation or date
wws.properties	Workstation Workload Summary report providing summary of job executions by workstation or date
zjrh.properties	Job Run History report for TWS/z
zjrs.properties	Job Run Statistics report for TWS/z
zwwr.properties	Workstation Workload Runtime report providing detailed job executions by workstation or date for TWS/z
zwws.properties	Workstation Workload Summary report providing summary of job executions by workstation or date for TWS/z

Each of the above properties files contains options that can be customised for the specific report. The table below discusses some of the common options found in each of the report properties files.

Option	Description
PARAM_ReportDescription	Specifies a description for the report – the default setting for all reports is “this is a description” which is not very useful!
PARAM_AppendSelectionCriteria	Specifies if the report selection criteria should be included in the report output – set to false by default
PARAM_Toc	Specifies if the table of contents should be included in the report output – set to false by default. Set this option to true for long HTML based reports as it generates hyperlinks to different sections of the report
REPORT_TYPE	Defines which report to produce for the built-in reporting
PARAM_FILTER_<type>	Various report specific filtering options such as username, date and time range, etc.
REPORT_OUTPUT_FORMAT	Format of the generated report – can be set to html, csv or pdf
OutputView	View format for generated report – can be set to table or charts for table and graphic views respectively. Not all reports support the charts format.
CSVSeparator	Separator character for CSV type reports – default value is a comma “,”. This should be changed if generating detailed reports that include JSDL job definitions to a character like “|” to be correctly loaded into applications like Microsoft Excel
PARAM_ReportLayout, PARAM_ReportHeight, PARAM_ReportWidth	Used to define the page layout for PDF based reports. Can be commented out for HTML or CSV based reports.
PARAM_UserLimit	User specified limit for maximum rows or sections to be processed – default value is report dependent

In addition to the above options, each report type has additional report specific options. Refer to the report properties file for details of these additional options.

Generating a report

To generate a report use the command syntax shown below (entered on a single line)

UNIX/Linux

Windows

Replace <properties.file> with the name of the required properties file as shown in the table above.

Specify the name of the file to contain the generated report, without a file type as this will be added automatically based upon the report output format (e.g. html, csv or pdf)

Replace the <output_path> with the path to create the generated report output

 

Report samples

The following screen shots provide samples of the different reports. To view a larger version of the screen shot click the image.

 

Audit Reports

TWS Audit Summary Report

TWS Audit Detail Report

 

Workstation Workload Reports

Workload Summary Report

Workload Runtime Report

 

Job Reports

Job Run Statistics Report

Job Run History Report

 

Custom reports

Custom SQL Report