IBM® Tivoli® Software

Maximo Asset Management – Version 7 Releases

V7.5 Report Feature Guide

Version 4

Pam Denny
Maximo Report Designer/Architect
 CONTENTS

Revision History vi

1 Overview 7

1.1 Installation.................................................................................................8

1.2 Report Execution......................................................................................11

1.3 Report Queue ..........................................................................................13

1.3.1 Property Settings...................................................................................... 13

1.3.2 Cron Task ................................................................................................. 14
1.3.3 Report Queuing Process ............................................................................ 15

1.4 Report Design Repository .........................................................................16

1.5 Request Page XML ...................................................................................18

1.6 Report File Structure ................................................................................21

1.6.1 Your Custom Reports and the Report File Structure .................................... 24

1.7 Report Designer Overview ........................................................................28

1.8 Version 7.5 Report Types...........................................................................31

1.8.1 Parameterized Reports – Type 1 ................................................................ 32

1.8.2 Application Reports – Type 2 ..................................................................... 34
1.8.3 Both Application and Parameterized Reports – Type 3 ................................ 37

2 Report Scheduling 40

2.1 Schedule Report.......................................................................................41

2.1.1 At This Time ............................................................................................. 41

V75x_Designer371_Report Development Guide

2.1.2 Recurring.................................................................................................. 42
Emailing ................................................................................................................ 44
Email Notes ........................................................................................................... 46
Validation.............................................................................................................. 46

2.2 Manage Scheduled Report ........................................................................48

2.3 Execute Scheduled Report ........................................................................50

2.4 View Scheduled Report - Emailing .............................................................52

2.4.1 Report Schedule Limits ............................................................................. 55

2.4.2 Scheduled Reports and Time Zones ........................................................... 56
2.4.3 Schedule Only Reports .............................................................................. 58
2.4.4 Schedule Only Reports – Reserved Processing Time.................................... 61

3 Report Security 64

3.1 Which security groups can run reports? ......................................................64

3.2 What reports can security groups execute? .................................................65

3.3 How Security and Report Access Work Together .........................................66

3.4 Security Notes – Data Restrictions .............................................................68

4 Importing Report Designs into the V75 Database 73

4.1 Set Up: reporttools.properties ..................................................................74

4.2 Import Command Utility ...........................................................................76

4.3 Export Command Utility ...........................................................................78

4.4 Update Reports Utility ..............................................................................82

5 Report Administration Features 83

iii
 5.1 Report Description and Name....................................................................84

5.2 Record Limits...........................................................................................86

5.3 Report Priorities .......................................................................................88

5.4 Report Sequencing ...................................................................................89

5.5 Parameters – Bound and Unbound.............................................................91

5.6 Individual Report Performance ..................................................................94

5.7 Report Usage ...........................................................................................95

5.7.1 BIRT Report Usage Report......................................................................... 96

6 Report Administration Actions 97

6.1 Security Actions .......................................................................................99

6.1.1 Setting Individual Report Level Security ..................................................... 99

6.1.2 Setting Application Level Security ........................................................... 100
6.1.3 Setting All Application Level Security....................................................... 101

6.2 Viewing Report Security by Security Group...............................................102

6.3 Individual Report Importing thru Report Administration.............................103

6.4 View Report Dependencies Action ...........................................................105

6.5 View Library Files Action .........................................................................106

6.6 Set Report Schedule Limits .....................................................................107

6.6.1 Managing Report Schedule Limits............................................................ 108

6.7 View Scheduled Reports - Administrator ..................................................109

V75x_Designer371_Report Development Guide

6.8 View Report Processing ..........................................................................110

6.8.1 View Report Processing – Cancelling Report Jobs...................................... 112

6.8.2 Additional details on Report Cancellation ................................................. 114

6.9 Deleting Reports ....................................................................................116

6.9.1 Deleting Enterprise Reports..................................................................... 116

6.9.2 Deleting Ad Hoc Reports ......................................................................... 117

6.10 Duplicating Reports................................................................................119

7 Miscellaneous Features 120

7.1 Report List Portlet ..................................................................................120

7.2 Multi KPI Report Linkage ........................................................................122

7.3 Property Files and Cron Tasks..................................................................123

7.3.1 Key Report Property Settings – Direct Print, Direct Print with Attachments 124
7.3.2 JVM System Properties ........................................................................... 125

7.4 Cron Tasks.............................................................................................126

7.5 Functionality not Supported....................................................................127

Reference Materials 128

© Copyright International Business Machines Corporation 2013

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule
Contract with IBM Corp.

v
 REVISION HISTORY

Date Version Revised Comments

By
August 2013 4 PD Updates include (1) reformat of document (2)
additional details on request page xml (3) updated
property settings (4) Updated reference URLs
July 2012 3 PD Updates include (1) Updated Email Note section on
page 45 to include more details on
mxe.email.content.type setting (2) Updates to
property settings for Version 7.5.0.3
May 2012 2 PD (1) Included information on downloading portrait
templates from ISM Library (2) Updated Cron Task,
property settings, and JVM Settings
March 2012 1 PD (1) Removed diagram on page 72 which was no longer
applicable (2) Additional information included on page
81, with details on how to update the import/export
utilities for use with application server security (3)
Added information on report import on JVM restart on
page 73 (3) Updated report reference materials section
May 2011 PD Original Release
V75_Report Feature Guide

1 Overview
In the Version 7.5 (V7.5) Releases, BIRT (Business Intelligence Reporting Tool) is the embedded reporting
tool. BIRT is an Eclipse-based tool for designing and viewing reports. The BIRT report engine uses XML
report definitions to produce reports in a web-based report viewer in HTML.

To understand the reporting process, it can be broken down into the five major components shown below.

Configuration
Configuration involves the architecture of the entire system; including the application server and database,
and the variety of ways it can be configured to meet your performance and volume requirements.

Design
The design process involves an analysis of not only how the report should display, but also how it is
accessed within the applications, what types of parameters it should use, and the sql it utilizes.

Development
The development of a report design file is done within the BIRT report design tool. In this stage of the
reporting process, the developer takes the designer’s inputs and translates them into the report design file.

Administration
Report administration includes not only the functionality to register and maintain the report file produced
by the developer, but also to manage the entire reporting process. This includes functionality like enabling
record and schedule limits, and monitoring report usage.

Execution
The last stage of the reporting process is when users execute reports from the different access points in the
applications, including toolbar icons, report menus, and start center portlets and kpis.

This guide details the embedded BIRT reporting functionality by focusing on two of the five major
processes: Execution and Administration. The guide will first start with an overview of the Execution of
reports. This includes topics of installation, execution, emailing, scheduling and database and both
delivered and recommended custom file structures.

Then, administration will be detailed. These specific topics will include security, importing and exporting,
and the multiple actions and functionality available within the Report Administration application.

The other three reporting processes areas - Configuration, Design and Development – each have their own
separate guide or guides detailing their unique functionality. Information on these can be found in the
Reference Material Section at the end of this guide.

7
1.1 Installation
There is no separate installation process for either the BIRT Engine or BIRT Reports. Both components are
installed through the standard Maximo Install Process. The process below depicts the three main steps in
enabling the report engine, and populating the report database tables.

Report Source <V7>\reports\birt

RPT Design Files
Libraries
Property Files

1. Run maxinst.bat

Creates Report Text Database Entries

REPORT
REPORTLOOKUP
REPORTLABEL

2. Deploy Maximo Ear File

Initializes BIRT Report Engine

Creates Report Design Database Entries

REPORTDESIGN
REPORTDEPEND
REPORTPARAM

Updates any Changes to

REPORT
REPORTLOOKUP
REPORTLABEL

3. Generate XML in V7 Report Admin Application

Creates Report Request Pages

REPLIBRARY Presentation in Database
V75_Report Feature Guide

Each of these three steps is described in detail below:

1. In the first step, the maxinst process is performed. This process creates the database entries in the
REPORT, REPORTLABEL and REPORTLOOKUP Tables.
a. To enable potential localization, these three tables are populated during the maxinst process.
b. The information for the REPORT and REPORTLOOKUP tables comes from each application’s
reports.xml file.
ex. <V75>\reports\birt\reports\ASSET\reports.xml
c. The information for the REPORTLABEL table comes from the properties file.
ex. <V75>\reports\birt\reports\libraries\asset.properties

2. In the second step, the Maximo EAR File is deployed. This process initializes the BIRT Report Engine,
and imports the report designs into the database.

The Maximo Ear file contains the BIRT Platform

Classes. When Maximo is deployed thru the EAR File
Process, BIRT is automatically deployed also.

*NOTE: During startup, a copy of the BIRT platform classes is made to a temporary location on the Server.
These files are used to initialize the BIRT report engine. To specify the temporary file location, reference
the Property File Settings at the end of this document. Otherwise, the temporary location will default to
<c>:\temp

2a. The information for the REPORTDESIGN, REPORTDEPEND and REPORTPARAM tables comes from a
variety of places including the reports.xml files, the report design files and the system library.
<V75>\reports\birt\reports\ASSET\reports.xml
<V75>\reports\birt\reports\ASSET\asset_measurehistory.rptdesign
<V75>\reports\birt\libraries\libraries.xml

At the end of the second step, the BIRT Engine is embedded, and the report files have been placed in the
database.

9
Note: To verify report designs have imported, execute one of the sql statements below against the target
database:
Select reportname from reportdesign (to verify reports loaded)
Select * from report design (NOTE: This statement will take considerably longer as it will pull all the
reports.xml files, which are stored as CLOBs in the Database)

3. In the third step, an administrator, with security privileges, accesses the Report Administration
application. The administrator must then generate the Report’s Request Pages by clicking on the
‘Generate Request Page’ button in the lower right section of the page. This will create the
REPLIBRARY presentation in the database.

If the request pages have not been generated, and a user tries to run a report from an application, they
will receive the error below: ‘BMXAA3515E – The report is not available because its request page has
not been generated.’

Notes:
1. For additional information on the request page xml, reference section 1.5 below.
2. For version 7.5, the recommended screen resolution for the applications has changed to 1280x768.
V75_Report Feature Guide

1.2 Report Execution

When a report is executed, the process below occurs.

1. The user first submits his report request. This can happen by clicking on the Submit button on the
Request Page, or by clicking on one of the Report Icons in the application’s toolbar.
This request is passed through to the report service.

2. The report service queries the database for the report design file.

3. The report design XML file is extracted from the database. It is stored in a temporary location within the
application server.

4. The XML design file is updated with information passed from the application.
This includes the user’s locale, time zone, parameter info, etc.

Note: This is a temporary update of the xml file only for this particular report instance. There are no
updates made to the actual report design file stored in the database.

5. The report is then executed, and displayed to the user in a separate browser session.

Notes:

11
1. When immediate reports are executed, these temporary files are removed from the file server via a
cleanup mechanism. This mechanism deletes the reports when any of the following occur:

A. If the user runs the same report multiple times, the previously run report information from the
temporary folder will be removed.

B. If the user signs out, all the temporary report information related to all the reports that the user
has run from the browser will be removed.

C. If the user session times out (which is by default, 30 minutes), then all the temporary report
information related to all the reports that the user has run from the browser will be removed.

D. If the server is restarted, then all the temporary report information related to all the reports
that any user has run from the browser will be removed.

2. This process will vary slightly depending on:

A. If the report is scheduled
B. If the report is enabled for Browser View, Direct Print or Direct Print with Attachments.

In these cases, the access point for the submitted job will vary (for example – a Browser View
report request is initiated from an icon in the toolbar versus an immediate job is initiated via the
Submit Button on the Request Page.)

3. You can specify the location for the report temporary files by setting the JVM System Property,
mxe.report.birt.tempfolder property. Details on this can be found in the Properties Section of this
document.

4. There are a variety of ways in which systems can be configured to use the report engine. These include
the ability to separate out the Report Server on its own, or to configure a clustered environment, and
utilize the Cron cluster to run scheduled Reports. Each of these configurations and others are contained in
the Report Performance Guide. This document is available along with other report support
documentation at the url referenced at the end of this document, which is also copied here:
http://www.ibm.com/developerworks/wikis/display/maximo/Report+Reference+Materials
V75_Report Feature Guide

1.3 Report Queue

When numerous reports are executing in the report engine at once, performance can be adversely
affected. Therefore functionality is enabled which limits on the number of jobs that can be executed at
any given time. This will distribute the load on the server from reports, and reduce the amount of wait
time for report users.

Report Queuing is used to handle the load of report jobs. The Queue Manager oversees the report queuing
process. It is responsible for managing the scheduled jobs that enter the queue and the workers who
process the scheduled jobs.

1.3.1 Property Settings

A. The property, mxe.report.birt.maxconcurrentrun, manages the number of BIRT Immediate and
Scheduled Reports that can be run concurrently. By default, the number is set to 5.

This property file is used by each application server. So, if there are 4 application servers running, the
maxconcurrentrun property applies to each app server. Each server would be added as a separate value in
the Instance Properties section.

B. A second property, called mxe.report.birt.queueidletimeseconds, is used by the Queue Manager. Its

default value is 60 seconds. This value is the frequency that the Queue Manager polls the queue for new
reports jobs.

13
1.3.2 Cron Task
The Report Queue Lock Release Task has a parameter, Lock Interval Minutes. This is used to determine if
Locked Report Jobs should continue to be executed, or if they should be stopped, and re-entered into the
queue.
V75_Report Feature Guide

1.3.3 Report Queuing Process

The Report Queuing Process is made up of two components: Scheduled Report jobs and Immediate
Reports jobs. Scheduled Report Jobs are controlled by the Queue Manager. The Queue Manager and
Worker Threads Do Not apply to Immediate Report jobs. The Queue Manager and worker threads apply
ONLY to Scheduled Report jobs.

To limit the number of report jobs that can be executed on a server at any time, the maxconcurrentrun
property setting is used. By default this value is set to 5. Before Immediate Report Job Requests are
accepted, the availability is checked to see if the immediate job can be processed or not. This is done using
the formula:

# Actively Running Scheduled Jobs + # Immediate Jobs < maxconcurrentrun

If # Actively Running Scheduled Jobs + # Immediate Jobs < maxconcurrentrun, the Immediate Job is Processed.

If # Actively Running Scheduled Jobs + # Immediate Jobs = maxconcurrentrun, the Immediate Job is not Processed.

Immediate Job
Submitted

Is there
Availability?

# of Worker Threads
# of Immediate Report
SUM Jobs + processing Scheduled
Jobs

No Yes

Total = maxconcurrentrun Total < maxconcurrentrun

Prompt End User Process Immediate

with Action Dialog Job

Cancel Report Schedule

Job Report Job

15
1.4 Report Design Repository
To support the execution of reports, a repository is necessary to hold the report design files. In V75, the
database is the repository for the report design files. During the deployment of the Maximo Ear File, an
import process occurs, which brings the report design files, and any of their dependant report files (ex.
libraries or resource files) into the database.

Additionally, a number of other database tables are required to support the reporting functionality,
including security, scheduling, processing and usage tables. The top level diagram below highlights these
key reporting tables, followed by a description of each.
V75_Report Feature Guide

REPORT: ParentTable

REPORTDESIGN: Report design’s XML

REPORTDEPEND: Dependencies of report designs (ex. MaximoSystemLibrary)
REPORTPARAM: Report design parameters

REPORTLABEL: Text values of report titles and column headings.

L_REPORTLABEL: Localized text values of REPORTLABEL.
REPORTLOOKUP: Text values of report parameters.
L_REPORTLOOKUP: Localized text values of REPORTLOOKUP.

REPORTADHOC: Contains design information on ad hoc report (ex. Sort, group, filtering) for future
editing
REPORTADHOCFIELD: Details fields used within ad hoc report design

REPORTAPPAUTH: Security group authorizations on report application security level

REPORTAUTH: Security group authorizations on report level
REPORTOSAUTH: Security group authorizations for Report Object Structures used in Ad Hoc (QBR)

REPORTJOB: Lists jobs that are currently being executed.

(Used for View Report Processing Action in the Report Administration application.)

REPORTUSAGELOG: Detailed information on executed BIRT Reports. Information is held in this table
until the REPORTUSAGECLEANUP Cron Task removes the entries.

REPORTDS: Data Source Information for multiple databases.

REPORTDSPARAM: Data Source Parameter Information on multiple databases.

REPORTLISTCFG: Lists Reports displayed in Report List Portlet of Start Center

REPORTSCHED: Report schedule information

REPORTPROCRESERVE: Holds reserved processing times for complex, batch reports.

REPORTPROCSCHED: Shows available schedule time for complex, batch reports

REPORTOUTPUT: Details on executed report

REPORTOUTPUTCNT: Content of executed report
REPORTOUTPUTHAUTH: Lists users who have access to executed report

REPORTRUNQUEUE: Report queuing

REPORTRUNLOCK: Processing information of queued report
REPORTRUNPARAM: Parameter information of queued report

17
1.5 Request Page XML

The information below provides additional details on the request page xml.
What is the Request Page XML?
Report request pages enable a user to input parameter, schedule and email inputs for reports. Report
request pages vary by the type of report that is used (BIRT, Cognos or Custom) and by the types of
parameters that are used.

The report request page information, including the parameter input dialogs, for all reports is held in one
XML structure in a library called REPLIBRARY. This REPLIBRARY presentation is often referred to as the
Request Page xml.

How is the Request Page XML generated?

The request page xml is generated with the Report Administration application. To do this, an
administrator, with security privileges, accesses application. Then, on the bottom right hand side of the
page, the administrator clicks on the ‘Generate Request Page’ button. This creates the REPLIBRARY
presentation in the database.

Before the request page xml is generated, the REPLIBRARY presentation in the database has no values.
After it is generated, the REPLIBRARY is created, and reports can then be executed.

What happens if the Request Page XML is not generated?

If the request page xml has not been generated from the Report Administration application, you will be
unable to execute reports.

Specifically, what will occur is that the list of available reports will display to a user. However, if they select
a report, an error will display as the request page is unavailable. The error is: BMXAA3515E – The report is
not available because its request page has not been generated.
V75_Report Feature Guide

Where is the replibrary located?

The REPLIBRARY presentation is a system library, stored in maxpresentation. It is not associated to a
specific application. You can export it via the Application Designer application from Maximo by selecting
Export System Library from the action menu, and choosing REPLIBRARY.

How can I confirm if a report’s request page is in the replibrary?

To confirm if a request page is included in the presentation, export the presentation. Then, search thru the
xml by looking for the applicable reportnum. Each report dialog ID for a request page is in the format
reportd<reportnum>.

The reportnum value is not available from the Report Administration application. However, you can find it
by querying the database with a script similar to as shown below:

select reportnum from report where reportname=<value> and appname=<value>

How can I customize the replibrary?

Currently the replibrary presentation is not externalized or recommended for modifications. However, if
you must make changes to it, you can export and import it through Application Designer. First, generate
the request page xml from the Report Administration application, then export the presentation. Apply
your customizations, and then reimport the presentation through Application Designer.

*NOTE* If you re-generate your report request pages from Report Administration, it will overwrite any
customizations you have made to the presentation. Additionally, if you have a multi-language
environment and use QBR Ad Hoc reports, the cron task REPORTADHOCLOC will overwrite this
presentation

When do you need to generate Request Page XML?

The request page xml should be generated under any of the following conditions

1. When you perform a new Maximo installation

2. When you apply a Maximo Fix pack
3. When you add a new enterprise report. This could be a BIRT, Cognos or any other external reporting
tool you use through a Integration.
4. When you modify any of the report’s parameters or parameter settings. These settings include:
Parameter name, attribute name, lookup, Display name, Display Sequence, Required, Multi-lookup
enabled, default value or Operator
5. If you change the settings for a report including: Schedule Only, Priority, No Request Page
6. If you add or delete Reserved Processing Times for a Schedule Only Report
7. If you have a multi-language environment, please see the requirements for these environments in the
section below.

When do you NOT need to generate Request Page XML?

The request page xml does not have to be generated in these conditions

1. If you add a new JVM to a clustered environment. In this case, the JVM will take the request page xml
(REPLIBRARY) from the database.
2. If you modify any of the Browser View, Direct Print or Direct Print with Attachments settings.
3. If you modify the Use Where Clause setting
4. If you modify existing Reserved Processing Times for a Schedule Only Report
5. If you modify the report design file.

19
What are the Request Page XML requirements for Clustered Environments?
If you have a clustered environment, depending on the version of Maximo you are using, will determine
how request page xml generation functions.

Scenario 1: For Maximo 7.1.1.9 or later, or any of the Maximo 7.5.0.1 or later Releases
In a clustered environment, initially, you must generate the request page xml for each individual instance,
or all JVMs have to be restarted after generation of request pages in one JVM. However, when you add
new reports or modify existing ones, the request page xml needs to be generated on a single server only.
Reference: APAR IZ98911

Scenario 2: For Maximo 7.1.1.9 and earlier versions

In a clustered environment, initially, you must generate the request page xml for each individual instance.
Then, if you add new reports or modify existing ones, the request page xml must be generated on each
instance.

This occurs because after the presentation that contains the new report is built, it is saved to the database,
but it is only loaded into memory of the current Maximo instance. However, the other clustered instances
are unaware of the new presentation as it is not in their memory. These other clustered instances must
either be restarted (to load from the database again) or have their request page xml regenerated.

These two scenarios are explained in this example. An environment has three JVMs which are started.
These three JVMs are JVM_A, JVM_B and JVM_C. The administrator generates request pages on JVM_A.

-In Scenario 1, if you are on Version 7.1.1.9 or higher, or 7.5.0.1 or higher, no additional actions need to be
taken. JVM_B and JVM_C will recognize see the newly generated request pages.

-However, in Scenario 1, if you are on versions earlier than 7.1.1.9, or Version 7.5.0.0., JVM_B and JVM_C
will not know that in JVM_A request pages are generated. In this case, you will have to regenerate the
request pages on JVM_B and JVM_C.

What are the Request Page XML requirements for a Multi-Language Environment?
1. If you have a multi language environment, additional steps must be taken to create the request page
xml for each of the individual languages. These steps include signing into Maximo in each of the individual
languages, and then generating the request page xml for each language. This process insures that the
report request pages will display properly for each individual language.

Additionally, whenever any new report is added, the request page xml must be generated for each
language for all reports. Not just the new report. Additional details on the request page xml language
requirements can be found in the Maximo Report Localization guide available here
http://www-01.ibm.com/support/docview.wss?uid=swg21505045

2. Additionally, in a multi language environment, if you utilize QBR Ad Hoc reporting, the request page for
the QBR report is initially generated in the base language of the user creating the report.

Starting in Maximo 7.5.0.1, a new cron task is available to generate the QBR request pages in multiple
languages. The cron task is called REPORTADHOCLOC. It determines the frequency that newly created
Ad Hoc Report Request Pages are enabled in multi-language environments. This cron task is for multiple
language environments only. In a single language environment, this cron task can remain inactive.
V75_Report Feature Guide

1.6 Report File Structure

Delivered Report File Structure
The reporting infrastructure contains not only the files required for the report engine, but also the design
files, libraries, templates and various tools used during the reporting processes. The 75 file structure is
shown and detailed below.

birtplatform: Contain files required for the BIRT engine. These files should not be modified.

eri: Files for configuring V7RI (Integration used when a Version 6 environment uses V7 Reporting)

libraries: Library, Resource and Property files required to support the report design files.

A. Library. Libraries store re-usable components, functionality and images. Reports that
use libraries are automatically updated with the latest library information when they are
executed.

One system library, called MaximoSystemLibrary.rptlibrary, is used. It contains two core

items:

1. Master Pages. This defines items like the margins for printing, and the controls used
for page formatting (ex page n of m). This is contained in the library because it is used on
all reports, and rarely changes.

2. Themes. This contains the style sheet, which defines the font type, font size and other
text characteristics to be used in the reports. The theme in the library is referred to as the
style in the report design. The maximoTheme contains the specific colors and formatting
for the reports.

The libraries.xml file is used for importing the MaximoSystemLibrary file.

B. Resource. Resource files are .gif or .jpg images used in report designs. Two resource
files are used. These are IBM_logo_black.gif and tivoli.gif, which are the two logos
displayed at the top right and left hand corner of each V7.5 Out of the Box report.
Resource files are imported into the database as zipped files.

Clients may want to customize the reports to use their own corporate logos. Information
on how to do this is in ‘Changing Logos in BIRT Reports’ referenced on the last page of
this document.

21
 C. Properties File. Each of the application’s properties file is contained within this
subdirectory. Property files contain the text values of the report titles, and
column/Subheader labels.

Property files are created at the application level, and not at the report level, because
reports within an application frequently share the same text label values. (Example:
Asset Reports often use the same labels of Asset, Location, Site, multiple times.)

Reports: Contains Report Design files stored within their corresponding application subfolder. Also
contains the reports.xml file with information on each report used for importing.

Scriptlibrary: Contains script library classes and mxreportdatasources.properties file used by BIRT Designer
tool to connect to databases.
For the integration of BIRT, when a report developer creates a report, a Custom Scripted Data Source is
used. This Scripted Data Source is called ‘maximoDataSource’.

A scripted data source is used to fully utilize the specific functionality for Runtime Data Translation and
Time Zone Conversions. An example of this functionality is the localized values of Description. For
example, if you are running both English and Spanish environments, and the English values of descriptions
been localized into Spanish, the scripted data source is required to insure the localized Spanish
descriptions display in reports.

The classes for the scripting are contained within this subfolder.
 V75_Report Feature Guide

Templates: Twelve Template files are delivered, and must be used if you are creating any custom reports
directly in the Report Design Tool. Each template type is delivered in both landscape and portrait format.
The landscape file is listed in the table first, followed by the portrait template

Note: You must use these templates when creating custom reports as they contain the Maximo data source,
and scripting classes required for reports to properly execute from within the V75 instance. If you do not use
them, your custom reports may initially execute from within V75, but your reports will eventually fail as the
report jobs will not be processed correctly.

File Name Template Name Description

maximoListReport Tivoli Maximo List Report For simple listing report - traditional row,
Template column format
maximoListReportPortrait

maximoGroupReport Tivoli Maximo Grouped Report Same as listing report - but contains
Template sections for grouping results - ex. group by
maximoGroupReportPortrait site or status

maximoSubreport Tivoli Maximo Subreport Used for complex reports, including detail
Template reports
maximoSubreportPortrait

maximoChartListReport. Tivoli Maximo Graphic List Simple listing report, which includes a
Report Template graphic for either bar, line or pie chart
maximoChartListReportPortrait before the report's results.

maximoChartGroupReport Tivoli Maximo Graphic Grouped Grouped report with graphic for either bar,
Report Template line or pie chart before the report's results.
maximoChartGroupPortrait

maximoChartSubreport Tivoli Maximo Graphic Subreport Complex report with graphic for either bar,
Template line or pie chart before the report's results.
maximoChartSubreportPortrait

Tools: Files used to importing and exporting report design files from database. More information on these
tools is contained in the Import and Exporting sections.

Additional Notes on Report Source:

1. There are no separate library or design files for the three database types that are supported. Within the
report source, the sql is being written in ANSI Standards, so it will be applicable to any of the three
database types.
• There may be a few reports where the database specific sql is required. In these cases, the sql
will be written with conditional statements (ex. If database type = IBM DB2®, do this. If not,
do this + that…etc)

23
1.6.1 Your Custom Reports and the Report File Structure
The section above reviewed the delivered report source and file structure. However, you may need to
create or modify reports to meet your individual business needs. In this case, you will have new or
modified report design files, reports.xml and properties file.

To streamline the administration and maintenance of your custom report design files, and also to insure
that they are properly updated in future hot fix and fix pack releases, it is highly recommended that you
implement a file structure similar to what is shown below.

For New Custom Reports – Report Design and XML file

For any new custom reports you create, it is highly recommended that you assign them unique report file
names, and also create new reports.xml files for these. You may want to make them unique by utilizing
your company name, or another identifier in their file name and reports.xml.

To illustrate this, let’s imagine you created a new report for the Location application, which is titled
Location History Report. To highlight this as your report, you may want to call it
location_history_abc.rptdesign, where abc is the name of your company.

Additionally, when you create its reports.xml, instead of modifying the existing location’s reports.xml for
this new report, create your own unique reports.xml titled reports_abc.xml, which is located under the
directory: <V75>\reports\birt\reports\LOCATION
V75_Report Feature Guide

For New Custom or Modified Reports – Properties file

As stated above, the properties file contains the text for the title and labels within your report. This is used
to insure the values can be properly localized.

When you create custom reports, you can choose to either modify the existing properties file for the
application, or create your own new properties file. To determine the solution that is best for your
environment, you may want to take the following into consideration

1. A single report design can only reference a single properties file.

2. Applications can utilize multiple properties file. During the command import process, all
properties file for the application will be imported.
3. Report titles, labels may be modified during release, fix pack or hot fix updates. Therefore, if
you modify the delivered properties file with your customizations, your updates may be
overridden during an update.

Based on this, you may want to create your own custom properties file, by copying the delivered file and
then renaming your properties file to quickly identify it.

Then, when your developer adds new labels for your new reports, he will add them to the custom
properties, location_abc.properties as shown below in the Report Designer.

By creating unique file names and unique reports.xml files for your custom reports, they will always be
imported during the import process. The import process imports any xml file it sees – not just the
delivered reports.xml file. Additionally, when modifications are made to the out of the box reports, you
will not have to merge your changes – they will be kept separate.

25
Notes:
1. More details on how the developer creates the custom properties file is in the V75 Report
Development Guide. You can find this and other report reference materials at this url:
http://ibm.co/14r8jK7

2. For details on importing your new or customized reports thru the Report Administration
application, reference the ‘Individual Report Importing thru Report Administration’ section at the
end of this guide.

For Modifications to Delivered Reports - Report Design and XML file

You may decide that you simply need to add or remove fields to a delivered report to meet your data
analysis requirements.

In this case, it is recommended that you follow the same process as above, in making a copy of the original
report design file, renaming it to a unique file name, and then making the customizations to the new report
design file. This same process would apply to the reports.xml file. Make a copy of it, rename it, and make
the change to the new reports.xml file.

Following a similar example as above, you need to modify the Location Availability Report. To do this, you
1. Copy the loc_availability.rptdesign file
2. Rename the copied version to loc_availability_abc.rptdesign
3. Make the changes to the report in the Report Design tool and save.

For the reports.xml file, you

1. Copy the reports.xml file
2. Rename the copied version to reports_abc.xml.
3. Find the location availability entry and modify it to use the new file name,
loc_availability_abc.rptdesign and any other changes to the report and parameters. Delete all
other references to design files that you have not modified.

Your resulting file structure will look something like this

An example of the copied and modified reports_abc.xml is below. Note again, that this version of the
reports.xml should only include the entries for the files you have updated. Do not leave in entries of the
report design files you have not modified.
V75_Report Feature Guide

Notes:
1. With this approach on duplicating and modifying the report source and files, you will end up with two
entries of the location availability report in your database and also in the Report Administration
application. These are the original report, and the report you have customized.

A. To only make the customized version (loc_availability_abc.rptdesign) available to your users,

only enable report file security to this file in the report administration application.

B. Or, you could remove the original file (loc_availability.rptdesign) from the original reports.xml
file. However, you would need to repeat this process for each future fix pack or release upgrade
you receive.

2. For recommendations on the properties file for modifications to delivered reports, please see the
section above titled ‘For New Custom or Modified Reports – Properties file’

27
1.7 Report Designer Overview
The BIRT Report Designer is an Eclipse Based Tool that Java Developers use to create and customize V7
Enterprise reports. In V7.5.0.0 thru V7.5.0.2, BIRT Designer 2.3.2 is used, which is based on Eclipse 3.4.2.
Starting with V7.5.0.3, BIRT Designer 3.7.1 is used, which is based on Eclipse 3.7.1.

To enable the report integration, custom library, style sheet, templates and data sources have been
created. These files insure a consistent, look and feel for all reports, plus most importantly, insure that
reports will execute correctly from the various applications. These files must be used on all custom reports
to insure the report integration executes properly.

The BIRT Designer is installed on the client machine of the Java Developer(s) who will be creating or
customizing reports. It is not required to be on each user’s machine – only those users who will be
physically creating or customizing reports. Since the BIRT Designer executes off the Eclipse Framework,
Eclipse must first be installed on the Java Developers Workstation, and then the BIRT Designer is installed
within Eclipse. The client must also have a JRE version installed.

Note:
Details on downloading and configuring the BIRT Designer to work with Version 7.5 can be found in
the V75 Report Development Guide. You can find this and other report reference materials at this url:
http://ibm.co/14r8jK7
V75_Report Feature Guide

There are three files created for report designs.

1. Design File. This contains the details on the report – its sql, grouping, sorting, hyperlinking, etc. An
example of this is the asset_availability.rptdesign file.

The Design File uses a custom scripted data source. This is done to fully utilize the specific functionality
for Runtime Data Translation and Time Zone Conversions.

The scripted data source calls the JDBC Connection to execute the report against the V7.5 Database.

2. Properties File. This contains the text values and keys of each column label and report title. There
is one properties file for each application that has reports. This enables the same label values (ex.
Description) to be used only once. This property file is one of the major components used in
localization. An example of this is the asset.properties file.

3. Reports.xml File. This file defines the report information (its design file name, its parameters, its
application etc.) and is used to import the report files into the database. There is one reports.xml
file for each application.

29
The chart below shows how the report files interact with each other. At the top level is the design file,
which always has the file extension of .rptdesign.

Each of the reports has a dependency on the Maximo® System Library File. A BIRT Design file can only
have a dependency on either another design file (.rptdesign) or another library file (.rptlibrary)

The Maximo System Library file has its own import file, called libraries.xml. If a change is made to the
Maximo System Library, the libraries.xml file is used to import that library change into the database.

The Maximo System Library file contains references to the resources, or image files. These typically have a
.gif or .jpg extension. When a resource file is imported into the database, the files are converted to .zip
format. (These files are stored as BLOB data types in the database.)

The properties files are also resource files. Properties files are referenced in the reports.xml which is used
to import the reports into the database.

File Name Dependency Resource Description Location**

Asset.rptdesign Asset List Design File reports
maximoSystemLibrary.rptlibrary Maximo System Library libraries
.gif/.jpg files Resources or Image Files libraries
asset.properties Asset Property file libraries
Reports.xml Information on report and its reports
parameters. Used for
importing

**Location in the chart has been condensed. Its full path is <v75>\reports\birt\....

Note:

1. More details on how to configure these files for your custom report needs is noted in the section titled
‘Your Custom Reports and the Report File Structure’.
V75_Report Feature Guide

1.8 Version 7.5 Report Types

Version 7.5 enables a variety of mechanisms for you to analyze the powerful data created by the 7.5
applications. These data analysis features include:

QBE – Query By Example. Using your application’s filter and/or query, you can immediately download your
results for additional analysis in Microsoft Excel.

KPI - Key Performance Indicators. Visual indicators displaying status against predefined targets.

RS – Result Sets. Using an application’s query, enable a set of fields or graphic for display on the Start
Center.

QBR – Query Based Reporting. Version 7’s version of Ad hoc reporting where users create their own reports
on the fly from within the various applications.

Enterprise Reports - Often referred to as transactional reporting, these are the day to day detail reports
users require to complete their business tasks. These reports may enable viewing of data in varying
perspectives thru the use of complex graphs, in depth calculations or scenarios.

While this guide covers an overview of BIRT Reporting, which includes QBR, it focuses on Enterprise
reports. If you would like additional information on these data analysis options, including QBR, you may
want to reference the documentation below:

1. V75 QBR Ad Hoc Reporting. Details how QBR’s can be created, their business rules, and how to
create ROS (Report Object Structures) which enable QBR reports.
2. V75 Upgrade Planning Guide – Details all the data analysis options available to you, including the
report integration options of Cognos and External Report Integration.

31
Report Parameters
Reports can execute against three different sets of parameter types. These types are:

1. Parameterized Reports
2. Application Reports
3. Both Parameterized and Application Reports

Each of these report types is reviewed below.

1.8.1 Parameterized Reports – Type 1

Reports that have user inputted parameters have values defined in the Parameters Section in the Report
Administration application. These values are contained in the REPORTLOOKUP table in the database.

The Security Group Access report is an example of a parameterized report. The report has four parameters
– Security Group, Independent, Password Duration and User Members.

Additionally, its Use Where Clause field is not enabled. Information on the Use Where Clause field is
located separately in this guide.
V75_Report Feature Guide

When the user executes this report, the report will collect the user inputted values for these four
parameters and use those as filters to run against ALL records in the database.

This report will always execute against ALL records – even if the user has a selected record set in his
application’s Query.

33
1.8.2 Application Reports – Type 2
For reports where no parameters are specified, the report executes against the current/selected/all (C/S/A)
record set passed from the application to the report server. This is often referred to as executing against
the ‘where clause’.

This SLA List report is an example of this type of report. When the administrator views its record, he sees it
has no values defined in the parameters section, and hence no values in the REPORTLOOKUP table. Also,
notice that for reports using the C/S/A Record Set, the Use Where Clause? Field is disabled.

Then, when a user accesses this report from the SLA application, its parameter section in its request page
is blank. Reports using current/selected/all records do not display any parameters on their request pages.
There is no input required from the user.
V75_Report Feature Guide

The Current/Selected Record Set is passed from the application to the report server. Ex. The user has a
selected query where ‘APPLIES TO = INCIDENT’ in the SLA App. He selects to run the SLA List report, and
the filter is passed in the where clause to the report. The report will then only display those records from
his query.

35
When a report developer defines a report to use the application record set, he does not define any report
parameters in either its report design or reports.xml file.

Additionally, application reports are the only type of reports that can use the quick access fields of Browser
View, Direct Print, Direct Print with Attachments and Record Limits. More information on these fields and
others are contained in the ‘V75 Report Toolbar Access_Direct Print and Related Information’ document
referenced at the end of this guide.
V75_Report Feature Guide

1.8.3 Both Application and Parameterized Reports – Type 3

This type of report enables an application record report to execute along with user defined parameters.

In this case, the report would have parameters defined in the Report Administration application, and the
Use Where Clause Flag would be selected. Both of these requirements must be met to enable the report to
execute against both the application AND parameter set.

The example below modifies one of the delivered reports Job Plan List. The delivered version contains no
parameters, but in this example, a parameter, Status, has been added to the Job Plan List report.
Additionally, the Use Where Clause flag has been enabled. The report will then execute against both the
User Inputted Value of Status + the application record set that is passed to the report.

*Note: In order to do this, to modify the out of the box report, you will have to (1) remove the Browser
View Settings and (2) update the BIRT Design File to call out the new status parameter.

37
To see how this report executes from the Job Plan application, follow the steps below:

A. Access the Job Plan application and form a selected record set by inputting a filter of ‘IT’ in the Job Plan
field. Three Records are returned.

B. Click run reports from the Action Menu, and select the Job Plan List report. When its request page
appears, enter a value of ACTIVE in the status parameter.
V75_Report Feature Guide

C. Click Submit. The Report displays in the Report Browser.

Notice that the report executed against both types of Parameters: The Selected Record Set of three
records, and the User Inputted Parameter of ACTIVE. The result in the report only displays two records.
(Selected record set of ‘Job Plan = IT’ and report parameter filter of ‘STATUS = ACTIVE’ .)

Parameter Notes

1. If you are going to create new, custom reports, you may want to review the ‘Designing V75 Reports’
document to help determine what parameter types (example: user inputted versus application) are best
for your individual environment. Information on this document is contained on the last pages of this guide.

2. None of the Out-0f-the-box Reports have the ‘Use Where Clause’ Field enabled.
• If you want to enable these types of reports, the flag must be set in the Report Administration
application or in the reports.xml.

39
2 Report Scheduling
Reports can be executed a variety of ways, including
(1) Executing immediately
(2) Executing a report at a single date/time in the future
(3) Executing a report on a recurring basis in the future

Running a report right now is called an immediate job, and passes a report job request to the report engine
immediately. The other two options – running a report at a single point in the future – or on a future
recurring basis – involve scheduling. The report schedule options are detailed below.

Scheduling Reports involve four distinct stages: Scheduling, Managing, Executing and Viewing.

Manage Execute
Scheduled Scheduled View Scheduled
Schedule Report Report Report Report

Report's Schedule
via Cron Task Email
Request Page Details Page
V75_Report Feature Guide

2.1 Schedule Report

2.1.1 At This Time
The first type of Schedule Report Request is an ‘At this time’ or ‘One Time’ Single Schedule Request. The
user enters a value for the future point in time that the wants the report to execute.

The value can either be entered by the user or selected from the date/time lookup.

Note:
A. When scheduling a report using the ‘At This Time’ single run option, the selected date/time must be
within 363 days of the current date. For example, if today is 5/25/11, the report must be scheduled to run
anytime before 5/23/11. If a report is scheduled on 5/28/11 to be run on 9/1/12, the report will unable to be
scheduled.

41
2.1.2 Recurring
The second type of schedule report request is a ‘Recurring’ schedule request. Recurring schedule request
occur at regular intervals – like once a week, once a month, or every Friday at 3pm.

Recurring schedule values must be selected via the lookup. A unique schedule lookup is available for
reports. It is similar to the Cron Task Scheduler Lookup. To prevent potential user schedule errors and
performance impacts, it does not include the cron task values of Every Second and Every Minute.

Once a user selects his recurring scheduled option from the lookup, it will display as ‘Selected’ on the
request page.
V75_Report Feature Guide

When the user clicks submit for either a single or recurring schedule request, he receives a confirmation
message:

Schedule Detail: Will open up the Schedule Detail dialog page where the user can review or edit his
schedule inputs
Delete: Will delete the scheduled report request
Cancel: Will close the window

43
Emailing
You have a number of options to select how your scheduled report should be received. You can choose to
receive your scheduled report in either pdf or xls file format in an email, or you can choose to access your
scheduled report via a file url.

Email with a file attachment

If you select this option, the scheduled report will be sent directly to your email in either xls or pdf file
format. With this option, the scheduled report can be sent to V75 Users or non-V75 users.
V75_Report Feature Guide

Email with a file URL

If you select this option, users will receive their scheduled report requests via a url. This url will enable
them to access and view their scheduled reports from the Report Viewer application within V75.

The key point on emailing with a file URL is that the user receiving the scheduled report url must be a V75
user. This is required because the access to the scheduled report url is within the Report Viewer
application. If you enter an email address for someone who is not a V75 user when specifying this file
format, the error message below will display:

45
Email Notes
Validation
The user’s inputs for his scheduled report request are validated to confirm:
A. If the ‘At this Time’ Option is selected, the inputted date/time is greater than the server’s current
time.
*Note: The scheduling time inputted is based on server time. More info on user’s locales and
time zone settings are contained in the sections below.

B. If ‘At this Time’ is typed in, both a date and time are entered.

C. At least one email address has been specified.

D. That the user scheduling the report has a valid email address in the email table. This address is
required to populate the ‘From’ Email section.

E. The recurring schedule report cannot be scheduled to occur for less than an hour.

F. If the ‘’Email file with URL’ option is selected, the recipients must be valid V75 users to access the
scheduled report output.

G. Each ‘At this Time’ scheduled report has to be scheduled within a time period of less than 363 days
from the current date. For example, if today is 5/25/11, the report must be scheduled to run anytime
before 5/23/11. If a report is scheduled on 5/28/11 to be run on 9/1/12, the report will unable to be
scheduled.

This is required to enable a 48 hour time period for the scheduled cron task to go back and check for
‘one time’ schedule requests if the Server goes down.

H. Additionally, no validation of input email addresses is performed. This means that if the user types
in the email address of an external contractor that he wants to email a report to – it is the
responsibility of the user to type the email address in correctly. Reporting functionality cannot be
enabled to validate each of the potential combinations of external email addresses.
V75_Report Feature Guide

Email System Property Settings

A. For report emailing to successfully occur, the smtp server must be defined in the System Properties
application as shown below.

B. Additionally, you may want to evaluate setting the mxe.email.content.type setting property from
text/html to text/plain. Changing to text/plain will enable your users to receive text that has been input in
a Report’s Email Comment section with carriage returns as shown below.

When mxe.email.content.type set to text/html, email comments received as:

This is a test. It shows how text displays using mxe.email.content.type. This is a test test.

When mxe.email.content.type set to text/plain, email comments received as

This is a test.
It shows how text displays using mxe.email.content.type.
This is a test test.

47
2.2 Manage Scheduled Report
After the report job has been scheduled, the user can then manage his scheduled report requests. This is
done through the Scheduling Status tab and/or the Scheduling Details.

The Scheduling Status tab is available in the Reports window, and only shows reports that are scheduled to
occur on a recurring basis, or at a time in the future.
• If a report has been scheduled to run once, and has been executed, it no longer displays on the
Scheduling Status tab.

In the ‘Schedules You Can Edit’ section, a listing of BIRT report schedules can be viewed and modified by
the user. This information is displayed in ascending order of next run time. The Next Run Time is a non-
persistent field that is calculated via the schedule cron task.

In this tab, the user will see all reports that he has scheduled – regardless of the application he is currently
in. In the screen shot above, scheduled reports from the Security, Asset and PO applications all display to
the user. This enables the user to have one central location to manage all his schedule report jobs.
V75_Report Feature Guide

The Schedule Details can be accessed through either the (1) Schedule Confirmation Message shown above
or (2) By expanding a record in the ‘Schedules You Can Edit’ Section of the Scheduling Status Tab.

The Schedule Details is shown below. From this window, the user can update his schedule report or email
criteria. Additionally, the scheduled report request can be cancelled.

Notes:
A. Report parameters are not displayed in the Schedule Status Window. Once the parameters are
inputted by the user in the Report’s request page, they are not available for viewing or for modification.

49
2.3 Execute Scheduled Report
A cron task is used to execute the scheduled reports. The cron task is called REPORTSCHEDULE.

A separate cron task instance is created for each scheduled report. Therefore, your number of cron task
instances will be very dynamic as it is dependant on the number of scheduled jobs at any point in time.

The REPORTSCHEDULE Cron Task is read only, and is not intended to be modified or used to manage report
schedules. Both the instance name and schedule values are auto-assigned values from the cron task.

A separate action is available in the Report Administration application for administrators to manage/delete
report schedule instances. This action is called ‘View Scheduled Requests’.

The Report Schedule’s Cron Task parameter values will vary widely from report to report. The number of
cron task parameters can vary significantly because reports which use User Inputted Parameters have
more parameters than those that don’t. Additionally, the report parameters could vary from within the
same report design as one scheduled job may only have a single parameter value, whereas another
scheduled job could contain multiple parameter values.
V75_Report Feature Guide

Notes:
Only Active Scheduled Jobs will be displayed in the Cron Task application. If a scheduled report job is no
longer active, it no longer displays. (ex. A non-recurring scheduled job that has been completed),

Report security (what reports a user has access to) is given by Security Group. However, because report
scheduling is user specific (what parameters they enter, who they choose to email the schedule report to
etc) scheduling will be by user. This means that the user will only be able to see which Scheduled Report
Jobs have only been input by them.

51
2.4 View Scheduled Report - Emailing
When a user schedules a report, its delivery format is either sent via an email as either a file attachment or
file URL. Emailing is only used for BIRT reports when they are scheduled. Emailing can not be enabled for
Immediate Report Requests.

Email with a file attachment

It the scheduled report was selected to be sent via a file attachment, the user would receive the scheduled
report output in either pdf or xls file format in their email as shown below.

Email with a file url

It the scheduled report was selected to be sent via a file URL, the user would receive the scheduled report
output in either pdf or xls file format in their email as shown below.

When the user accesses the url, it will take them to the V75 log in page.

After signing in, the user is brought directly to the Report Viewer application, where his scheduled report
output is displayed.
V75_Report Feature Guide

On the right most side of the screen, he can click on the download icon, and a window will appear
prompting him if he wants to open or save his report output.

An example is shown here where the user chooses to open the report output. He can then choose to save,
print or close the resulting report file.

53
Additionally, the user may find the need to access the scheduled report output at a future date. He can do
that by accessing the Report Viewer application within V75. This application can be accessed from the Go
To Menu (Administration – Reporting – Report Viewer), or by setting it up as a favorite application on the
Start Center.

Once you access the application, you can see the total listing of report outputs that you have security
privileges to view.

To prevent large number of scheduled report outputs from accumulating, a cron task is used to delete
these files on a configured time period. The cron task is called ‘Report Output Cleanup Task’ and its default
value is 7 days.
V75_Report Feature Guide

2.4.1 Report Schedule Limits

You can limit the number of report schedule requests your users submit thru the report schedule limit
functionality. By limiting them to a maximum number of scheduled jobs, users will only submit schedule
requests for reports they need, and delete requests for obsolete report jobs.

Users may submit recurring schedule requests for reports that they think they will always need – but once
the need for the report output goes away – they may forget to delete the scheduled report request.
However, the report will still continue to execute. This leads to wasted, unnecessary resources – as the
processing continues – while the consumption has stopped.

When scheduled report limits are enabled, and a user inputs a scheduled report request that exceeds his
maximum allotted number, he will receive a message as shown below. He will then have to review his
existing report requests, and delete one of them before he can submit a new request.

If a user is member of multiple security groups, the scheduled record limit for the user is the minimum
value set for the various security groups.

This functionality has been introduced in the 7.5 release. Therefore, if you are upgrading from 7.1x to 7.5,
your user’s scheduled report requests will upgrade as is. If you then implement this functionality, it will not
take affect until the user’s next new scheduled report request.

Details on how the report administrator can implement this are in the Report Administration Action section at
the end of this guide.

55
2.4.2 Scheduled Reports and Time Zones
When a report is scheduled, the scheduled date/time will be based on the Time Zone of the application
server.

For example, user Liberi is on Pacific Standard Time. The application server is on Eastern Standard Time.
The administrator, Wilson, is on Eastern Time.

User Liberi schedules the PO Status Details to execute on 4/6/11 at 4:00 PM. When her scheduled report
request is submitted, it is stored in the database with a scheduled time of 4/6/11 7:00PM EST (the time of
the application server).

When Liberi views her schedule details, it will show as 4/6/11 at 4:00 PM – the date she scheduled the
request.
V75_Report Feature Guide

However, if the administrator, Wilson, views the scheduled report requests in Report Administration, each
request will display the server time that it will execute. So in the case of Liberi’s 4pm Pacific Standard
Time, it will display/execute at the server time of 7:00 pm Eastern Standard Time.

Scheduling Notes:

1. The Maximo Server and the Database Server must be configured in the same time zone.

2. If a scheduled job executes, but does not email the output to the user, the failure will be logged in the
REPORTUSAGELOG Table. Only one field is currently included in the REPORTUSAGLOG table to track
failures – whether those failures are due to the report not executing or not emailing.

3. The Report administrator can view and manage future Scheduled Report Jobs in the Report
Administration application via the ‘View Scheduled Reports’ action. Details on this are in the Report
Administration Action section at the end of this guide.

57
2.4.3 Schedule Only Reports
You can configure complex, batch reports to only be executed via Report Scheduling. This will prevent
users from running large, complex reports during peak use of the application, database and report server,
which can negatively impact overall system performance.

Before this functionality is described, let’s review how this could be applied. Each of you has a wide range
of complexity in reports. Some reports are very simple, like list reports or single grouped reports, whereas
others are very complex due to the number of subreports they encompass or the hierarchy levels they span
through. This Report complexity is defined by the processing the report has to do – not by the number of
records it displays. So, for example, a fifty page list report could execute ten times faster than a complex
two page report due to the processing defined within the report’s design.

The pie chart below represents a sample set of reports. Standard, transactional reports are displayed in
blue, with complex reports in red, and the most complex reports in yellow. These complex reports are time
consuming to design and develop, and are continually analyzed for performance efficiencies. These are
often referred to as batch reports, as they traditionally execute overnight due to their large processing
requirements.

Range of Report Complexity

Standard Transactional
Complex
Very Complex

Because of the processing load complex reports have on a system, they can now be configured to only be
executed via report schedules. Additionally, the very complex reports can be configured to only execute
via schedules at specific times of the day. This will minimize the impact these complex reports have on
overall system performance.

The next few pages describe how to enable this functionality.

To enable the ‘Schedule Only’ functionality for a complex report, access the Report Administration
application and locate the report. The example below will use the Cost by System report.

First, click Preview from the list tab to see what the report’s request page looks like. Notice that three
Execution Options display – Immediate, Schedule At this Time, or Schedule Recurring. These are the three
default run report options.
V75_Report Feature Guide

Now, enable this report for ‘Schedule Only’. Close this window and on the Report Tab, enable the value for
‘Schedule Only’.

Save the change, and generate the Request Page XML. Click Preview, and an updated request page
displays. Now, the ‘Immediate’ Report Execution Option is no longer available. Only the two options for
scheduling are presented to the user.

59
 k-

Note that the ‘Schedule Only’ functionality for a report can also be viewed and enabled on the
Performance Tab of Report Admin.

Notes:
1. If the Schedule Only field is enabled, the following fields can not be enabled:
No Request Page?
Browser View?
Direct Print?
Direct Print with Attachments?

This is because each of those fields relies on the request page NOT being displayed to the user. In the case
of Scheduled Only reports, the request page needs to be displayed so the schedule inputs can be made –
therefore, these options are not available.
V75_Report Feature Guide

2.4.4 Schedule Only Reports – Reserved Processing Time

In addition to enabling ‘Schedule Only’ functionality for very complex, batch reports, you can also
configure what times are available for the report scheduling. This will prevent users from scheduling report
jobs of complex reports at the peak times of server use. For example, you may not want your users to run
very complex batch reports on Monday morning, when many users are trying to execute their daily or
weekly transactional reports.

Reserved Processing time will detail the busy days and time within a week that server processing time is
reserved for immediate report jobs and other maximo application functionality. This functionality will be
based on days of the week. It is not based on calendar days, example January 1, due to fluctuations with
calendars and holidays.

Reserved Processing Time can be set on any day of the week (Monday thru Sunday) and for any amount of
time less than 24 hours. On the Performance Tab in Report Administration, the administrator will click
New Row and specify the day of the week, and the times during that day that report processing is NOT
available for that report job. This functionality is enabled by individual report because of the range of
report complexity.

To set the reserve processing time for a report, the administrator must first enable the Schedule Only?
Flag. Then, under the ‘Reserved Processing Time’ section, click new row to define the Day, Start Reserve,
End Reserve and Total Reserved Time.

After the values are defined, the administrator saves the change, and must regenerate the request page
xml.

61
What the Reserved Processing Times Looks like to a User
Report users want to know when they can execute a report, so the reserved processing times on the report
request page - - will show instead as the Schedule Availability.

The Schedule Availability shows the opposite of the reserved processing time in Report Administration. In
Report Administration, the administrator is concerned with reserving time that the report should NOT be
enabled to execute.

On the report request page, the user will also see the time zone in which the report availability was SET.
This may not match the time zone of the user. However, it is expected this functionality will be enabled on
complex reports executed by fairly technical users, who have an understanding of time zone impacts.
V75_Report Feature Guide

Notes:

1. Due to potential conflicts with varying time zones, and the complexity involved with Daylight Savings
time being utilized in some time zones but not others, the administrator can only reserve processing time
for each report using the same time zone.

This means that if he reserves a processing time of 7 AM to 4 PM EST for the Asset Cost Rollup report, any
other reserved processing time made for Asset Cost Rollup must be made in the EST time zone.

3. Due to the wide range of unique environments and requirements that each of you may have, no out of
the box reports delivered have this functionality enabled. It is meant to be a configurable option that you
can enable for your individual business environments.

4. After a ‘Schedule Only’ report has been scheduled, its available processing time will not show on the
‘Scheduling Status’ Tab. If the report schedule needs to be modified, it is recommended that the original
report schedule be deleted, and a new one input.

63
3 Report Security
Report security enables users within security groups to see and execute the reports that they have access
to. There are cascading levels of report security, with the first two levels being -

1. Which security groups can run reports?

2. What reports can security groups execute?

These two access levels will first be discussed, and then information on how data restrictions and report
interact will be detailed.

3.1 Which security groups can run reports?

From the Security Group application, the administrator defines which security groups have ‘Run Reports’
access to the various applications. This is shown below where the OPSMGR security group is given
Run Reports security access to the Assets application.

Once this access is granted, a member of this security group will be able to see the ‘Run Reports’ action
from the Action menu of the application.
V75_Report Feature Guide

3.2 What reports can security groups execute?

After granting Run Report security access in the Security Group application, the administrator then defines
which specific reports each security group can access. This report security can be set at
The Individual Report Level
All Reports registered to an application
All reports for all applications the security group has access to

These three different levels of report security access are defined in the Report Administration application.
This level of security enables the members of the security group to see and execute a list of specified
reports in the Reports window. In this example, the OPSMGR group was given access to All reports in the
Asset application, and they have a choice of 20 different reports to choose from.

Notes:
1. This report security access is for view and run access only - it does not give the security group the
ability to delete a report he has access to.
2. Each of the ways the administrator can set these levels of report security is described in the
Report Administration Action section below.

65
3.3 How Security and Report Access Work Together
After security groups have been granted report security privileges, users will be able to access the report
capability in a number of different ways. Four ways in which reports can be accessed are:
(1) Reports Window – On Demand Reports Tab
(2) Report Menu
(3) Report Icons from an Application’s toolbar
(4) Preview Button from Report Administration

The security for each of these options is described below:

(1) Run Report List and (2) Report Menu

The list of reports that the user has access to will be derived from
(1) the security groups that the user belongs to and
(2) the report authorization granted to those security groups from the REPORTAUTH and
REPORTAPPAUTH database tables.

(3) Report Icons from the Application’s Toolbar

If a user does not have security access to a report, the report Icons ( or ) will not be visible to
them on the application’s toolbar.
V75_Report Feature Guide

(4) Preview Button from Report Admin

The Report Administration application manages all reports – their report settings, parameters, security
access and design files. Therefore, if an administrator is granted access to the Report Administration
application through the Security Groups application, they will be able to see ALL registered reports. This
means that if there are 100 reports registered, the administrator can see all 100 reports within the
application.

However, you may not want the administrator to have security rights to each report. Therefore, report
security is applied in the Report Administration application at the report Submit level.

This means that an administrator can take action on a report (ex. Add or delete a parameter) that he does
not have access to, and preview it. But as soon as the administrator clicks on Submit on the request page,
if he does not have security rights to that report, an error message will display

67
3.4 Security Notes – Data Restrictions
Data Restrictions can be enabled to restrict what database records individual security groups see. These
restrictions can be used to configure your environment for your unique business needs.

Data Restrictions are set in the Security Group Application, and can then be applied to the various
applications. There are three different levels of data restrictions, which are
(1) Set Data Security, or ‘Qualified’ Object Restrictions
(2) Row Level Data Security, or ‘Hidden’ or ‘Read Only’ Object Restrictions
(3) Field Level Data Security. This is also known as ‘Hidden’, ‘Read Only’ or ‘Required’ Attribute
Restrictions.

For Reporting, only the first level or Qualified Object Restrictions can be applied. The other two levels can
not be enabled for reporting. This occurs because in addition to severely impacting performance, the
dynamic placement or non-placement of fields and rows would be extremely difficult to manage.

To enable Set Data Security for reporting, the following conditions must be met:

1. The Data Restriction can only be set on the main table (object) of the Application where the
report is registered to.

2. The type of Data Restriction must be qualified. It can not be Hidden or Read Only.

3. The Conditional Expression must utilize proper syntax.

4. The SQL of the Report Design must include the main table of the application.
V75_Report Feature Guide

Each of these conditions will be explained in more detail using the Inventory application. In this example,
the Security Group Purchasing needs to be set up so it only sees records from the Central Storeroom
Location, located in Site Bedford. Even though there are other storeroom locations in Bedford (ex. PKG
and GARAGE), the Purchasing Group can only see data from the Central Location.

To enable this, the administrator will first set the storeroom data restriction. He goes to the Security
Group application, and filters for Security Group Purchasing. He first confirms that they have all Options
Granted for the Inventory application on the Application Tab.

Next, he goes to the Data Restrictions Tab. He then enables the data restriction by implementing the first
3 conditions highlighted below:

1. The Data Restriction is set on the main table (object) of the application where the report is
registered to. In this case, it is the INVENTORY application.

2. The type of Data Restriction is set to Qualified.

3. The Conditional Expression utilizes proper syntax

Note: More details on Data Restrictions and the proper syntax for setting up Conditional Expressions are
contained in the System Administrator’s Guide in Chapter 2.

The administrator saves the new data restriction. Then, the administrator confirms that the Purchasing
Security Group has access to see specific Inventory Reports from the Report Administration application.
The View Group Security Action in this application shows that Purchasing has all access to reports in the
Inventory application.

After this has been confirmed, the administrator signs out.

69
One last step must be completed to insure the data restrictions apply to reports. That step requires that
the main table of the application that the report is registered to must be included in the report design’s sql
statement. Continuing with our example, the Inventory Balance report will be used, and it must be
confirmed that the main table of the Inventory application (INVENTORY) is contained in its report’s sql.

To do this, either open up the Report Design file (inventory_balance_tbl.rptdesign) located in

<V7>\reports\birt\reports\INVENTOR in the BIRT Designer or in a text editor.

Scroll down to find the report’s sql and confirm that INVENTORY is included. In this case, it is, so the data
restrictions can properly pass to the report.

If the main table was not included in the report’s sql, it would have to be added in order for the data
restrictions to pass properly.

Note: If modifications are made to the report’s sql, the updated design file must then be imported into the
database. More information on this is contained within this guide.
V75_Report Feature Guide

Once the setup items are completed, confirm that the data restrictions apply to reports. To do this, a
member of the Purchasing Security Group, Liberi, signs in. Liberi goes to the Inventory application, and
selects Run Reports from the Action Menu. She selects the Inventory Balance report, and enters
parameter values for the Storeroom (Central) that she has access to.

When she clicks Submit, the report displays with the values from the Central Location.

Liberi repeats this process by running the same report against a storeroom she does not have access to. In
this case, she runs it against Storeroom PKG.

71
When she clicks submit, the report initiates, but it does not display any data. This is correct behavior as
even though data exists, Liberi does not have security rights to view it.

nd rd
Finally, if you need to implement Hidden or Read Only Object or Attribute Restrictions (the 2 and 3 Data
Restriction Level) for a specific security group, there are a few different options available. These options
will be explained by using an example from the Work Order Tracking application.

The Scheduling Security Group should have access to the Work Order Tracking application, however, this
group should not have visibility on the Planned Labor and Actual Labor Costs within this application. These
fields should be hidden from the Scheduling Security Group. This is called ‘field level’ security. Once this
field level security is implemented, members of the Scheduling Security Group do not see these fields
within the Work Order Tracking application.

However, this field level security can not be applied to reports. Therefore, if there are reports that contain
Planned Labor and Actual Labor Costs (like Work Order Details), the following Options exist:

1. Do not grant Report Security access to these reports to the Scheduling Security Group.

2. Make a copy of the Work Order Details report and re-name it to something like Work Order
Details – Scheduling Group. Then, remove the planned and actual labor costs from this report.
Grant report security access to the Scheduling Group to this new report that has the cost
information removed.

More details on Data Restrictions and the proper syntax for setting up Conditional Expressions are
contained in the System Administrator’s Guide in Chapter 2.

Notes on Data Restrictions and Reporting:

1. Collections are a 'special' type of object restriction related to collections of CIs, assets or locations. A
collection restriction is at the set and row level - creating one creates a number of hidden and qualified
object restrictions behind the scenes. Collection data restrictions are also not applied to reporting.

2. If you are hyperlinking to a report, and data restriction is in place, make sure to qualify the table (object)
name. If it is not qualified, the hyperlinked report may display blank data.

*Note: For more details on enabling hyperlinks in reports, reference the V7 Report Development Guide.
V75_Report Feature Guide

4 Importing Report Designs into the V75 Database

As noted earlier, the repository for the report design files is the V75 database. These files are extracted at
run time to meet the individual’s report request.

During the V7 installation process highlighted at the beginning of this guide, the import process is
performed. Additionally, when a JVM is restarted, the reports directory is checked to see if any new
reports have been added. If new reports are detected, the import process will be initiated to bring in the
new files only. A complete import of all reports is not done on a JVM system restart.
Note: A JVM restart will not import updated report design files. If you have updated your report
design files, you need to import them thru the import utilities or via the Report Administration
actions described below.

However, administrators and developers may need to import or export report design files from the V75
database repository outside of any installation or JVM restart process. For example, they may need to
export existing or ad hoc report design files from the database so the design files can be modified in the
report design tool. Then, once the updates are made, the administrator would import the updated design
file into the database.

Importing and exporting of the report design files can be done via command utilities. A key component of
these utilities is a properties file called reporttools.properties. This property file contains information on
the application server, the file directory where the reports designs are either coming from or going to, and
username and password information on the user performing the operation. This process is shown in the
diagram below.

73
4.1 Set Up: reporttools.properties
Before the importing or exporting processes can occur, the reporttools.properties file must be configured
by following the steps below

Browse to the tool location ...<V75> \reports\birt\tools. Locate and open the reporttools.properties file
shown below. Enter the standard values required for this file.

Within this file, there are entries for the user who has privileges to import and export reports. This user is
defined in the Security Group Application in Maximo per the privileges highlighted below.

You have the option to both input the username and password into the property file, or not.
V75_Report Feature Guide

If you enter the username and password values in the reporttools.properties file, they will be used when
the import or export utility is used. This is shown in the example below.
# User that has access to perform the operation
maximo.report.birt.username=wilson

# Password of the user that has access to perform the operation

maximo.report.birt.password=wilson

If you do not enter the username and password values in the reporttools.properties file, you will be
prompted to enter them when you execute the import or export utilities per the example below.
# User that has access to perform the operation
#maximo.report.birt.username=abcabc

# Password of the user that has access to perform the operation

#maximo.report.birt.password=abcabc

75
4.2 Import Command Utility
Importing brings reports into the database. If the report design is new, a new record will be created in the
database. If the report design exists, the import process will over-write the existing file. After the import is
complete, the updated or new files will be located in the REPORTDESIGN table, which holds the design
files, resource files and library files.

If you have a large number of reports to import, you may want to use the import command utility. The
import process uses the reports.xml file to import the report design files in the database. A reports.xml file
is available for each application that has reports, and is located in the directory <V75>reports\birt\reports.

The reports.xml file references each report design for the individual application. If a report design is not
referenced in the reports.xml file, it will not be imported during the command utility process. Details on
updating the reports.xml file for any new report files you may create can be found in the ‘V75 Report
Developer’s Guide’ referenced at the end of this document.

To use the import utility, follow the steps below.

1. On the V75 server, open a command prompt window and change to the folder
<V75> \reports\birt\tools.

Then, run any of the following variations of the import utility

A. importreports
Imports all reports, libraries and resource files in the single import action.

B. importreports help
Displays details on the various import commands

C. importreports libraries
Imports all the libraries

D. importreports reports
Imports all the reports

E. importreports app [appname]

Imports all reports for a specified application.
This command is useful if you only want to import reports for a single application. For example:
importreports app CONFIGUR will import all the reports in the CONFIGURATION application. These are
the reports found in the directory below:
<V75> \reports\birt\reports\CONFIGUR
V75_Report Feature Guide

4. After the import is complete, sign into your Application as the administrator. Go to the Report
Administration application, and generate the XML for the reports. This completes the process for
importing new or updated design files.

Additionally, you can view that the import occurred by looking at the ‘Last Import Date’ field for an
individual report record. This displays the date/time of the last import.

Note: Details on importing a report thru the Report Administration application are provided in the ‘Report
Administration Action’ section toward the end of this document.

77
4.3 Export Command Utility
You may want to export report design files for a report developer to modify, or you may to extend an Ad
Hoc or Query Based (QBR) report. For example, a user asks that an Ad Hoc report he created be extended
to include a bar chart to the report. To save the developer time, the Ad Hoc report can be exported, and
opened in the BIRT Designer. The developer can add the bar chart, and then import the design file back
into the database as an enterprise report.

Exporting of reports is enabled as a utility only.

To enable exporting, go to the server, open a command prompt window and change to the folder <V75>
\reports\birt\tools. Then, any of the commands below are available:

A. exportreports
Exports all libraries and reports.

B. exportreports report
Exports all reports.

C. exportreports library
Exports all libraries.

D. exportreports app [appname]

Exports all reports for the specified application.

E. exportreport report [appname] [reportfilename]

Exports single, specified report for the specified application.

The report will be exported to the location defined by

(1) the reporttools.properties file and
(2) its report folder that it is registered to in the Report Administration application.
V75_Report Feature Guide

Export Example
The example below will use wotrack.rptdesign to show the exporting functionality. The
reporttools.properties file has been set to use the output location shown below in red:

maximo.report.birt.outputfolder= c:/V75/reports/birt/reports

Additionally, the wotrack.rptdesign is located in the following applications and report folders:

Report Name App Name Report Folder Description

woprint.rptdesign QUICKREP WOTRACK Quick Reporting

woprint.rptdesign CHANGE WOTRACK Change

woprint.rptdesign RELEASE WOTRACK Release

woprint.rptdesign ACTIVITY WOTRACK Activity

woprint.rptdesign WOTRACK WOTRACK Work Order

When the various exports commands are executed, the following will occur:

1. exportreports
Exports all reports to c:/V75/reports/birt/reports and their various subfolders

AND Exports all libraries to c:/V75/reports/birt/libraries

2. exportreports report
Exports all reports to c:/V75/reports/birt/reports and their various subfolders

3. exportreports library
Export all libraries to c:/V75/reports/birt/libraries

4. exportreports app WOTRACK

Exports all reports registered to WOTRACK to c:/V75/reports/birt/reports/WOTRACK

5. exportreport report WOTRACK woprint.rptdesign

Exports woprint.rptdesign to c:/V75/reports/birt/reports/WOTRACK

79
Additional Export Details
A. If a report structure is not available in the location where the export is to occur, a file structure will
be created.

B. If a reports.xml is not available in the location where the export is to occur, the reports.xml will be
created.
• This may occur if you create a new custom report design file, and register and import the
report thru the Report Administration application.
• If you do this and you make subsequent changes to the parameters or settings of the
report in the Report Administration application, make sure to export the report design
file so any changes you are made are captured in the new reports.xml file.

C. If a reports.xml file does exist - the export will not overwrite the existing file.
• In this case, a new one will be created using a –filename. Ex: In WOTRACK folder, if
reports.xml exists and a new export occurs, a new reports-wotrack.xml file will be
created.
This new reports-wotrack.xml will take precedence over the reports.xml file during any
future importing actions.

D. Both the import and export command utility tools use HTTP, not RMI, to support application
server security. Only BASIC authentication is supported.

To enable the utilities for use with application server security, you must modify
<V75>\applications\maximo\mboweb\webmodule\WEB-INF\web.xml.

Open the file with a text editor and search for "AppServer security". Follow the instructions under the
NOTE.
V75_Report Feature Guide

Importing of the design files and any dependant report files (libraries, resource files) can be done in two
ways - (1) Bulk - Thru Command Utilities or (2) Individually – Through an action in the Report
Administration application. The table below describes the differences between the two.

Type Bulk Import Individual Import

Description To import multiple reports or libraries. Import To individually import a single report or library.
options include all reports/libraries, libraries
only, reports for a specified application.
Access Command Utility available from Action Available from Report Administration
<V7>\reports\birt\tools application.
Where Used …when a number of new reports are created for ...when an administrator needs to import a single
a Cloned application. The administrator has report file or library. This may be a new report, or
access to the application server, and wants to an update to an existing report. Additionally, the
import all the new reports for the Cloned administrator may not have access to the
application at one time. application’s console, so he can not utilize the
command functions.

81
4.4 Update Reports Utility
Additional update utilities can be used to automate the process of applying updates to report designs,
rather than manually editing each report. These are known as update utilities, and supplement the
existing utilities of importing and exporting report designs. The update utilities are available for both
Enterprise Reports, and Ad Hoc or QBR Reports.

For enterprise reports, the four update utilities available are:

1. updatereports
Updates all reports.

2. updatereports savechanges
Updates reports and saves the modified reports to the database.

3. updatereports app [appname]

Updates all reports for the specified app.

4. updatereports app [appname] savechanges

Updates all reports for the specified app and saves the modified reports to the database

For Ad Hoc reports, the update utility available is:

1. updateqbrs
Updates all QBR report designs

Specific details on how you can use these utilities can be found in the Update Reports Utility document
located on IBM’s support website. Information on locating this can be found in the Reference Materials
section at the end of this document.
V75_Report Feature Guide

5 Report Administration Features

This section details the various features enabled within the Report Administration application.
Additionally, it provides more information on individual features including report names, sequencing,
priorities, application access and many other features.

83
5.1 Report Description and Name
When a user receives the listing of the reports that he has access to, the report’s description is displayed.
This value correlates to REPORT.DESCRIPTION., and an example is shown below.

The report’s description can be seen in the Report Administration application in the field next to the report
file name. Note however, that this is an optional field.

The report’s description can be null.

V75_Report Feature Guide

If its description is null, the value that will display to the end user is the report’s design file name which is a
required field. (REPORT.REPORTNAME). In this case, the value of jobplan_print.rptdesign is displayed to
the end user from the Run Report dialog.

If this scenario occurs, the user will be unable to filter his listing of reports from the dialog. If he tries to
filter and a reports’ file name is included in the list instead of the report’s description, an error will display
that filtering is unavailable.

85
5.2 Record Limits
Occasionally, users may inadvertently execute reports against large or very large record sets within an
application. This can cause negative performance impacts on both the application and database server.

An example of this scenario can be described using the Work Order Tracking application. In this case, a
user wants to print out 10 new work orders which were input during the night shift. However, the user
forgot to filter their query, and instead of submitting a Work Order Details Report Request for the only the
10 new work orders, they input a Work Order Details Report Request for all work orders, totaling over 2500
records. And because the Work Order Details report is a very complex report, this request can tie up the
application and database server for some time.

To minimize these errors, record limit functionality is available so you can define exactly the maximum
number of records a report can execute against. This functionality can be set for reports that use the
application record set. (For details on an application record set, reference the section titled ‘Application
Reports – Type 2’)

The record limit functionality can be quickly defined for a report in the report administration application by
following these steps:
1. Enable the Limit Record Flag
2. Input a value for the Max Record Limit. The value must be greater than 1, but there is no limit on
the maximum number that can be input.
3. Save the record, and regenerate the request page xml.

Note: This value can also be defined on the Performance Tab of the individual report’s record.

Then, when a user executes a report where these values are defined, a count of the user’s current record
selection is made from the application they are in. This value is then checked against any record limits set
for the selected report.
• If the current record set is greater than the record limit, a message is displayed to the
user to reduce his query.
• If the current record set is less than the record limit, the report is executed.

If a user tries to execute a report from the app against a record set of 100 records - and the report has a
limit of 50 - an error message will display: ‘BMXAA3412E – Result set exceeds maximum allowed count of
50 for the report. Please narrow your result set and request the report again.’
V75_Report Feature Guide

Notes:
A. To enable Direct Print (DP) and Direct Print with Attachments (DPA) Functionality, the Record Limit
flag must be enabled and a max record limit set.

B. A number of Out of the Box Reports have these values set. A listing of them can be found in the 7.5
Report Booklet referenced at the end of this guide.

C. The corresponding database fields enabling this functionality are:

REPORT.DETAIL = Limit Records YORN Field
REPORT.RECORDLIMIT = Maximum Record Limit

D. If a report has record limits enabled, it can not be executed from

1. The Preview Button in Report Administration
2. The External Reports Menu from the application

The report can only be executed from within the application so a count of its records is available before the
report is executed.

87
5.3 Report Priorities
A ‘Priority’ field is available in the Report Settings section of the Report Tab in Report Administration. This
value is stored in the Report table as REPORT.PRIORITY.

The report priority is used for report queuing. Based on ascending order of priority, report jobs are
prioritized in the reporting queue based on ascending order of priority. More details on Report Queuing
are available in the Report Queuing Section.

An administrator can assign priorities to reports other than BIRT. Priorities are not used in the out of the
box functionality, but you could use them to potentially extend the reporting functionality.
V75_Report Feature Guide

5.4 Report Sequencing

Report sequencing enables administrators to specify the order of the reports displayed in the Report Run
Dialog. By enabling the sequence field, you can manage the report display order, so users do not have to
filter or scroll through pages of reports to find their report. This enables users to quickly see their most
frequently accessed reports in the report display window.

The Display field applies to a variety of report types – BIRT, QBR, Cognos, or Custom. The Display Order
field is not required. If the Display Order is not specified, the reports will display in alphabetical order.
Also, the display order can be applied to some reports within an application and not others.

To enable this functionality, the administrator will define that Display Order field for Reports within the
Report Administration application.

For BIRT Reports, this functionality can be set in the application's reports.xml file and defined when the
report is imported. Its new database field is REPORT.DISPLAYNAME.

Unlike the report’s toolbar sequence value, the display order field does not have to be unique within the
application. This can make it easier for report administrator’s to manage the display of their reports as
new reports get added, and others deleted. The combination of the sequence field and the report’s
description (ascending order) will determine the display order of the reports.

The screens below show this functionality. Within the Asset application, the list of reports is displayed.
Sequence fields are not enabled, so reports display in alphabetical order.

89
Users however, want the ‘Summary of Asset Failures’ report to be displayed first. So, the administrator
accesses the Report Administration application, and sets its ‘Display Order’ Field to 1.

After saving and regenerating the request page XML, the Summary of Asset Failures report then displays
first in the list of Asset Reports.
V75_Report Feature Guide

5.5 Parameters – Bound and Unbound

As noted earlier in the guide, reports can have three different types of parameters which are
1. Parameterized Reports
2. Application Reports
3. Both Parameterized and Application Reports

As an administrator, it is important to understand that there are two types of parameterized values -
bound and unbound.

Bound parameters either

• exist in the main table of the application the report is registered to or
• exist via a maxrelationship that has been set up for the application.

To identify if an existing parameter is bound, look at its Attribute Name field in the Report Administration
application. Bound parameters will ALWAYS have the Attribute Name Field Populated – whereas Unbound
Parameters will NEVER have the Attribute Name field Populated.

Bound parameters are appended to the where clause. An example of a bound parameter is the Security
Group parameter in the Security Group report. Notice its Attribute Name field is populated.

91
Unbound parameters
• do not exist in the main table of the application and
• are not available through any relationship (defined in maxrelationship) for the main table.
Unbound parameters are not included in the where clause.

An example of an unbound parameter is the User parameter in the Electronic Signature Transaction report.
This parameter is unbound because it does not exist in the main table of the application (CONFIGUR) and
does not exist in one of the maxrelationship to this application. This is shown below. Notice that its
Attribute Name field is blank.
 V75_Report Feature Guide

The Chart below recaps each of the fields available for parameters in Report Administration, and whether
or not they should be populated for bound versus unbound parameters.

Bound Unbound
Advantage Can have lookups, and do not need to Flexibility.
be defined in report’s design.
Parameter Name Do not need to be defined in Report’s Must be defined in Report’s design file
design file
Attribute Name ALWAYS Populated NEVER Populated

Lookup Name Can either be populated or not Can only be used for Unbound Dates
(*DateLookup Only)

Operator (>, >=, <, <=) Optional NEVER Populated

Multi-Lookup Enabled? Yes or No Yes or No

Display Sequence Numeric Value Numeric Value

Override Label Any Text Any Text

Default Value Can either be populated or not. Can either be populated or not
*NOTE: Default Values are not *NOTE: Default Values are not enabled for
enabled for localization localization
Required? Yes or No Yes or No

Examples security_group.rptdesign eSig_trans.rptdesign

Parameter Notes:
1. The maximum number of parameterized values for a single report is 23. These include 15 Non-Date
Time Parameters, and 8 Date-Time parameters.

If more than the 15 Non-Date and 8 Date-Time Parameters are entered, invalid bindings will display on the
report’s request page.

2. Bound and Unbound parameters will behave the same way when a user enters values on the Request
Page. Specifically, this means that if there is a parameter for Status, the following will occur:

User entered parameter value Report Results

=APPR Records where status = APPR
APPR Records where status = WAPPR, APPR
%APPR Records where status = WAPPR, APPR

93
5.6 Individual Report Performance
Within the Report Administration application, a Performance tab enables administrators to quickly
monitor performance on individual reports.

The first section of the Performance Tab is Historical Values. This contains value information from the last
time the report was executed. In the example below, it shows that the ‘Work Order Details’ report
registered in the Work Order Tracking application was last executed by user Wilson on 4/4/11 at 11:55am.
The report executed in 5 seconds.

This information is held in the REPORTUSAGELOG table and can also be displayed by executing the
Report Usage report.

Enabling the display of these values quickly gives administrators a data point on how long reports are
taking to execute. This is valuable information in a development-type environment as administrators can
identify long-executing reports, and enable features like ‘Schedule Only’ or ‘Record Limits’ to minimize
their performance impact.

The second section of the Performance Tab is Settings. This contains the settings that directly impact
performance. These settings are also displayed on the Report Tab, but are also enabled here for ease of
use by the administrator. For example, if he sees a long executing report, he can quickly set its ‘Limit
Records?’ Flag here on this tab.

The third and final section of the Performance Tab is Reserved Processing Times. This is functionality
enabled for ‘Schedule Only’ reports. Details on this functionality are contained within this document.
V75_Report Feature Guide

5.7 Report Usage

You can monitor report usage to assist in answering key questions often raised by Development and IT,
including:

‘Which reports take the longest to execute?’

‘Who uses this report? If no one is using it, can it be archived?’
‘Are users taking advantage of the scheduling functionality? Or are they causing performance constraints by
always running reports immediately?’

Monitoring of report usage is enabled thru the REPORTUSAGELOG database table. Each time a user
executes a report, an entry is made in this table. This data includes when the report request was submitted
or scheduled, when it actually executed, how long it took to execute, and what server it was executed on.
This information is vital to answering the questions on report execution and performance above.

The REPORTUSAGELOG table can get populated very quickly as it records data whenever any report is
executed – whether it is an enterprise report or a Query Based Report. Therefore, a cron task is used to
delete the entries from the REPORTUSAGELOG table in a specified period of time. The cron task enables
you to configure both the frequency of the database cleanup and the length of time the usage records are
retained to a schedule that is best suited for them.

This cron task is called, REPORTUSAGELOG, and has a default value of 30 days.

95
5.7.1 BIRT Report Usage Report
The data in the REPORTUSAGLOG Table can be evaluated via a delivered report, called Report Usage
(reportusage.rptdesign). It contains information on reports that are executed immediately, scheduled to
execute at a future time, accessed via hyperlinks or are QBR Report Types.

One of the most important fields in the Report Usage Report is the Run Time Field. The data from this field
comes from REPORTUSAGELOG.RUNTIME, which is stored in the database in milliseconds. The Run
Time field is the amount of time the BIRT Report Engine takes to execute the Report, which is the
REPORTUSAGELOG.ENDDATE – REPORTUSAGELOG.STARTDATE.

If a user executes an immediate report, the runtime may be less than the physical time the user actually
experiences. This is because the report runtime does not include the time for tasks like opening up the
report browser, and copying the report temporary files. However because of the report scheduling
queuing process, this is the best consistent indicator of a report’s run time.

The Report Usage Report converts the runtime data from milliseconds to HH:MM:SS Format for ease of
analysis.

Query Based Reports (QBRs) are also captured in the Report Usage Table. Because these reports often
may be executed only a single time, their corresponding run times will be displayed in a separate section,
called ‘Transient Reports’ at the end of this Report.
V75_Report Feature Guide

6 Report Administration Actions

This next section highlights key Report Administration actions.

97
Action Description Where to find Details
View Report Processing Displays reports that are either being Page 110
processed by the report engine, or are in the
queue waiting to be processed
View Scheduled Reports Enables the administrator a view of all the Page 109
scheduled reports currently in the system.
Set Application Security Grants report security access to all reports Page 100
within a selected application
Set All Application Security Grants reports security access to all reports Page 101
for all applications that a security group has
access to
Set Report Schedule Limits Enables you to limit the number of report Page 107
schedule requests your users submit
View Group Security Displays which applications the selected Page 102
group has report access to
Import Report Imports individual report into V75 database Page 103
repository
Import Library File Imports individual library into V75 database Page 103
repository
View Report Dependencies Displays report files that the selected file is Page 105
dependant on
View Library File Displays all library files in V75 database Page 106
repository
Set Report Object Structure Report Object Structures (ROS) are base of Reference Document
Security Ad Hoc Reporting. Each application can have “V75 QBR Ad Hoc Reporting”
multiple ROS, so this action defines which
security groups have access to individual ROS
Configure Data Sources Enables use of non-production database for Reference Document
report execution “Enabling secondary
Database Configuration for
BIRT reports’
Duplicate Report Duplicates report entry for use in cloned Page 119
application or for modification of ad hoc
report
Delete Report Deletion of ad hoc or enterprise report Page 116
V75_Report Feature Guide

6.1 Security Actions

After the administrator has granted ‘Run Report’ security access in the Security Group application, the
administrator then defines which specific reports each security group can access. This report security can
be set at
The Individual Report Level
All Reports registered to an application
All reports for all applications the security group has access to

6.1.1 Setting Individual Report Level Security

After a report is imported or registered, the administrator can click on the Security Tab to grant access to
the individual report to security groups. The standard functionality of clicking ‘New Row’ adds a new entry.
Clicking on the lookup displays a listing of All Security Groups who have ‘Run Report’ Access for the
application the report is registered to.

99
6.1.2 Setting Application Level Security
To grant access to all reports within an application, click Set Application Security from the Action Menu in
Report Administration. This brings up a listing of all applications that have reports registered to them.
Select the application, and then click New Row to grant a new Group Access. Clicking on the lookup
displays a listing of all groups that have ‘Run Report’ Access to that application.

Additionally, select ‘ALL’ to grant access to all report types registered to that application – or select one or
more of the individual report types. At least one type must be selected.
V75_Report Feature Guide

6.1.3 Setting All Application Level Security

To grant access to all reports that a group has access via a single action, click Set All Application Security
from the Action Menu in Report Administration.

Select the security group or groups that you want to grant access to. Then, select ‘ALL’ to grant access to
all report types registered to that application – or select one or more of the individual report types. A
minimum of one option must be selected. The screen shot below shows the Bedford Site Security Group
which has been granted to access to all BIRT Reports for the applications that they have access to.

101
6.2 Viewing Report Security by Security Group
To view what applications a security group has report access to, click ‘View Group Security’ from the Action
Menu. Select a group, and a listing of all applications the specified security group has access to will display
by report type.
V75_Report Feature Guide

6.3 Individual Report Importing thru Report Administration

If you have modified only a single report, or are registering a small number of reports, you may want to use
the Report Administration application to import these report designs. To do this, locate the individual
design file, and from the action menu, select ‘Import Report’.

Browse to the location of the design file, and the report resource file if required. Follow the prompts in the
windows, and once complete, the updated design file will be imported in the database.

Notes:
1. Libraries must be imported before report designs. If the report design references a library that has not
been imported, the report design will not import.
- If the report references an existing library (MaximoSystemLibrary.rptlibrary) that is already in the
database, you do not need to import another copy of that library.

2. Importing overwrites the existing records in the database with the new design/and or dependant report
files.

3. Once the process is completed, the ‘Imported By’ and ‘Last Import Date’ fields will be updated with the
latest values.

4. If you are importing a new design file, you must first create its record in Report Administration, and then
import the file.

5. Do not copy/paste the location of any of the files to be imported. (Report Design File, Report Resource
File or Library File.) You must use the browse button to properly import the correct file.

6. You must import resource files are imported as .zip files. Resource files include property files and
images. If you are importing an existing report where no changes have been made to the properties file,
you do not need to reimport its property file.

However, if you have created a new properties file for your new or custom reports, as noted earlier in the
guide, you must first zip your properties file before importing it as shown below.

103
7. There is no validation on the report design’s file during the import process. Errors in the report design
file will import. It is up to the developer/administrator to insure that the design file is correct.
The import process only validates that the design file being imported matches the current record.
V75_Report Feature Guide

6.4 View Report Dependencies Action

You can view all the files that an individual report is dependant on by using the action ‘View Report
Dependencies’. These files could either be library files or other design files.

The example below shows the report dependencies for the Report Usage report.

The results for this view are derived from the REPORTDEPEND table.

In the bottom portion of the view, there is a ‘Dependant Library Files’ section. This will show any children
of the selected Library Files. For the out of the box reports, there are no values in this section. The
Maximo System Library does not have any children libraries, therefore, no values will display.

105
6.5 View Library Files Action
You can also view all the libraries that are in the report repository via the ‘View Library File’.
This view is useful when you may want to import a new report design file. You can view the action to
insure that all the libraries for the new report have already been added.

**NOTE: This will not show a listing of the report dependencies on this file. Instead, it gives a listing of the
libraries currently in the REPORTDESIGN Table (where REPORTDESIGN.ISLIB = ‘1’)
V75_Report Feature Guide

6.6 Set Report Schedule Limits

You can limit the number of report schedule requests your users submit thru the report schedule limit
functionality. By limiting them to a maximum number of scheduled jobs, users will only submit schedule
requests for reports they need, and delete requests for obsolete report jobs.

To configure this functionality, select the ‘Set Schedule Report Limits’ action. A dialog displays the
security groups who have run report access. Input any number for each unique security group. If you input
the number 0, the security group will not be able to input any scheduled report requests.

The example here shows that the Purchasing Security Group can enter a maximum of 4 scheduled report
requests. This includes both enterprise and ad hoc scheduled report requests.

107
6.6.1 Managing Report Schedule Limits
You can manage the schedule limits you have set for individual security groups through a delivered report
or KPI.

The Report Schedule Limits and Maintenance report details the number of security groups in the system.
It then shows the value and percentage of those groups with run report access, and those with scheduled
limits set. Administrators can use this report to quickly see the percentage of security groups that they
closely managing.

The delivered KPI below can also be configured on the report administrator’s start center to highlight those
security groups with the schedule limit value set.
V75_Report Feature Guide

6.7 View Scheduled Reports - Administrator

The Report administrator can view and manage all Scheduled Report Jobs via the ‘View Scheduled
Reports’ action. This enables the administrator a view of all the scheduled reports currently in the system.
It includes information on the type of Schedule (Recurring or Once) who scheduled it, and the report’s
priority.

This is useful for the administrator to view the report schedule load on the server, and potentially distribute
the load more evenly if required. Additionally, he has the ability to delete obsolete scheduled report
requests by clicking on the standard garbage can icon by the individual scheduled report request.

109
6.8 View Report Processing
You can view which reports are being executed via the ‘View Report Processing’ action. It shows all reports
that are either being processed by the report engine, or are in the queue waiting to be processed. The
records are displayed based on ascending order of Start Time. This display of records enables the
administrator to focus on those report jobs that are taking the longest time to execute.

The unique values in this view include:

Start Time: The date/time the report began executing.

For Immediate Jobs

The Start time is the time that the job is accepted when report processing is available.

For Scheduled Jobs,

The Start Time is the time that it (1) enters the report queue and (2) is locked by a worker thread
to begin processing. The time that it begins processing may not be the exact time it was
scheduled for due to unavailability. For example, if a report was scheduled to execute at 6:00 AM,
it may not actually execute until 6:01:46 – due to availability. So – the actual Start Time of a
report will not always be the Report’s scheduled time.

If a scheduled report job has (1) entered the report queue but has not been locked by a worker
thread to begin processing, its Start Time will be null. In this case, its Status will be queued.

Processing Time: The amount of time the report has been processing. This is a non-persistent field and
only displays for reports with a status of In-Process (INPROG). The processing time can be recalculated at
any time when the user clicks on the ‘REFRESH’ Button on the screen.
Processing time is calculated by:
Current Server Time – Start Time

Status: Status of the report Job. The Status Value List has values of:
INPROG: In Progress.
V75_Report Feature Guide

The status of a report job = INPROG if the report job is locked by a Worker Thread and is
being processed. Either immediate or scheduled report jobs can have a status of
INPROG.

QUEUED: In Queue, or waiting for report processing availability.

The status of a report job = QUEUED if the report job has entered the report queue, but
worker threads are not available to process the report job.

Only scheduled report jobs can have a status of QUEUED.

Immediate report jobs can not have a status of QUEUED, because if the immediate job
can not be processed due to any availability, the user will be prompted to either cancel
the report job or schedule it for later processing.

111
6.8.1 View Report Processing – Cancelling Report Jobs
After viewing the report jobs that are processing, administrators can cancel user’s report jobs by selecting
the Garbage Can next to its individual report request. However, each report job is unique, and depending
on its report design, and the exact functionality that is being processed, will determine if and when its
cancellation can occur. Depending on the function being processed by the report job determines if the
report can be cancelled or not.

Unique Events triggered from Cancelling Scheduled Report Job

When a scheduled report job is cancelled by the administrator, the following occurs.

1. An email is sent to the user who scheduled the report. The ‘To’ Email field is the Email address of the
user who scheduled the report.

2. The scheduled report job no longer appears in the ‘View Report Processing’ window.
*Note: There may be a time delay from when the administrator cancels the report until it is physically
cancelled. So – if the administrator immediately clicks ‘Refresh’ after canceling a report job – it may still
initially display. Depending on the report process that is executing in the background determines how
quickly the report can actually be cancelled.

Unique Events triggered from Cancelling Immediate Report Jobs

When an immediate report job is cancelled by the administrator, a variety of scenarios could occur
depending on what report process the report job is in at the time of cancellation (ex. either fetching or
rendering). It is highly variable depending on the individual report job and the processing point it is at –
when and if the report cancellation can occur.

Due to the wide range of scenarios available, the following could be seen to the user

1. The user could see a blank report browser like this

2. Or he may see a report browser that contains a few pages of report data (for example, pages 1 and 2
display data) but the balance of the report pages contain report titles only.
V75_Report Feature Guide

3. Or if the administrator cancels a report job that he initiated – the report browser window may still show
as processing, while the cancel dialog has a status of CANCEL for the report.

NOTES:

1. Again, depending on the report job and its processing point, there may either be delays in when the job
is physically cancelled to the user – or if it can be cancelled.

1. If an immediate job takes a long time to execute, and the user closes the report browser – but the report
will continue to execute in the background.

3. Report job cancellations are logged in the REPORTUSAGE Table.

113
6.8.2 Additional details on Report Cancellation

As noted previously, there are two types of report jobs – Immediate and Scheduled Jobs. Immediate jobs
are submitted for immediate display or printing, whereas scheduled jobs can either be one time (3/31/11
st
11:00 PM) or recurring (Every 1 Day of the Month at 7:00 AM).

Whether a job is scheduled or immediate is very critical to its ability to be cancelled. Immediate jobs can
only be cancelled if they are not in the Fetch Method processing of the report because scripted data
sources are utilized.

However, scheduled report jobs are managed by the Queue Manager, and can be cancelled by the
administrator no matter what stage of processing it is in.

To further explain the variation in immediate job cancellation, the diagram below shows the top level steps
in report processing for a simple report looks like:

If the report is immediate, and the administrator cancels the report job -
And the report job is not in the Fetch Processing, its cancellation request can be processed
immediately.

And the report job is in the Fetch Processing, its cancellation request will be delayed. The report
will finish the Fetch Processing, and as soon as it is completed, and the processing goes back to
the report engine, the report job will be cancelled.

Immediate Report Job Scheduled Report Job

Processing by BIRT Yes Yes
Processing by Fetch No Yes

Again, because each report and its data are unique, and some may utilize more fetch logic than others,
there are no standards that can be applied on when the fetch functionality occurs. Therefore, depending
V75_Report Feature Guide

on where the report is in its processing, there may be some delay until the report is physically cancelled
within the report Server.

Additional notes on Report Cancellation

1. If a user initiates either a Direct Print or Direct Print with Attachments job via an icon from the
application’s toolbar, the user is unable to cancel these report jobs because the report browser is not
displayed. In these cases, the report jobs can only be cancelled by the administrator under the three
scenarios below -

A. The job will be cancelled immediately if it is not in fetch processing and not in the printing
phase
B. If the job is in the fetch processing, it will be cancelled when it exits the fetch processing
C. If the report processing is complete, and the job has entered the printing phase, the
report job can not be cancelled. Only the printing job can be cancelled via the user’s
default printer dialog.

2. This functionality only applies to BIRT Reports.

115
6.9 Deleting Reports
Administrators may want to delete reports when they are no longer used or needed. Depending on the
type of report being deleted – either Enterprise or Ad Hoc – the removal process will vary slightly.

6.9.1 Deleting Enterprise Reports

An administrator may want to delete an Enterprise Report because it is no longer executed by users.
Enterprise reports differ from Ad Hoc Reports in that they are developed in the report development tool by
developers, and then imported into the V75 repository via the command utilities or report administration
applications.

Enterprise reports do not display the field ‘QBR Created By’ on the report tab.

1. To delete an Enterprise Report, locate the specific record and select ‘Delete Report’ from the action
menu.

Notice the example below does not display the field ‘QBR Created By’. If the report was an ad hoc report,
this field would display directly underneath the ‘Imported By’ field, highlighted by the red arrow.

2. After the report is deleted, to prevent the report from being re-imported again on Server Restart or
during a future patch release, its entry must be removed from the reports.xml file. The reports.xml file is
located in <v75>\reports\birt\<name of Report Folder highlighted above> -- which in this case is in
<v7>\reports\birt\PR.

The delivered file is shown below with the entry to delete highlighted in red.

2. After removing the entry from the reports.xml file, rebuild and redeploy the ear file.
V75_Report Feature Guide

6.9.2 Deleting Ad Hoc Reports

From within the Report Administration application, you can quickly identify ad hoc reports as their
‘Created By’ field is populated. You could sort on this field on the list tab or use a default query as shown
below to quickly identify them.

You can form your own application query to identify ad hoc reports using the simple sql statement shown
below.

117
You may want to delete an Ad Hoc (QBR) report is no longer used by the users who created them, or when
a user leaves his job position or the company.

The screen shot below is an example of an Ad Hoc Report. The message displays when the administrator
selects ‘Delete Report’ from the Action Menu for this report.

If you select No, the message will disappear and you will remain on the Report Tab.

If you select Yes, the report entries will be deleted from the V75 database

Additionally, if you select Yes, any scheduled job requests for this report will deleted.
V75_Report Feature Guide

6.10 Duplicating Reports

You may want to duplicate a report so it can be accessed from a cloned application. Or you may want to
duplicate an ad hoc report, so the duplicated report can be exported to the Report Development tool for
additional modification.

The items below are key characteristics to consider when duplicating a report

A. If you are duplicating a report so it can be accessed from another application, make sure the main
table name of the two applications is the same. This is required so the where clause can pass the
correct information to the application of the duplicated report.

For example, if you duplicated a work order report and registered it to the purchase order
application, the duplicated report would not execute from the purchase order application. This
occurs because the main table used in the work order report is WOTRACK, whereas the main table
passed from the purchase order application is PO.

B. When you duplicate a BIRT Report,

- The report file name will display exactly like the record it is copied from
- The application name and report folder will be blank.

C. You can then make any adjustments to the report entries, but you must specify an application
name (along with defaulted report folder) before saving.

D. If you do not change the report file name and use the same application as the duplicated record, a
message will display on saving that this is not a valid combination. (The combination of report file
name and application make the record unique.)

E. Once the user has a unique combination, you are able to save the record, and the duplicated
report will display on the screen.

F. When duplicating a report, the individual report security authorizations are not copied.

When duplicating reports, a copy of the duplicated report’s design file is made in the REPORTDESIGN
table. If you want to use a different report design file, make sure to Import the correct design either via the
Action menu in Report Administration, or via the Import Command Utility.

119
7 Miscellaneous Features

7.1 Report List Portlet

You can configure Start Centers for your individual security groups by creating individual templates (tabs)
for users to quickly view and access applications and data. One of the primary purposes of the templates is
to show data via KPI Displays, which provide immediate, visual status of particular business metrics.
Another purpose is to enable quick access to applications, result sets or reports.

The report list portlet enables a listing of reports on the Start Center. With this functionality, you can
configure a listing of your individual, most frequently used reports for quick and easy access.

This functionality can be described by using the example of an SLA Administrator who wants to configure a
template for his SLA Related Activities, including a listing of his favorite SLA reports for quick and easy
access.

To enable the Report List Portlet, security rights need to first be granted to each Security Group who will
use this functionality. (In this case, it is the SLAADMIN group). To do this, follow the steps below:
1. Access the Security Group Application.
2. Select the Security Group. On the Applications tab, enter ‘report list’ in the description field.
3. When the results return, select Report List Setup Application. This is the Report List Portlet.
4. Grant access to ‘Read/Modify access to Report List Portlet’ and save.

After granting the security group access, sign out of V7.5 to refresh the settings. The next time you sign in,
the Security Group should have access to the Report List Portlet.
V75_Report Feature Guide

To enable the report list portlet, click on the Change Content/Layout Section of the template.
Select the ‘Report List’ from the Available Portlet window.

This enables the Report List Portlet to display on the Start Center.
Then, click on the Edit icon, and add the frequently accessed reports for display on your portlet.

Note: This list of report that displays are only those that you have security rights to execute.

After saving the selections, your favorite reports are displayed on his Start Center for quick access.

121
7.2 Multi KPI Report Linkage
You can hyperlink to a related report or KPI, when multiple KPIs are displayed in list type format within a
KPI Graph or List Portlet on a user’s Start Center. This enables you to drill down into additional details on
the KPI, which can be critical for KPI’s in red or yellow status.

This functionality is shown below. Notice that some KPIs have Related Reports and KPIs, and others do
not. For those KPIs where the hyperlink is enabled, you will see the name of the related report or related
KPI thru a mouse over which enables the report or kpi description to display.

You define the related kpi or report that the kpi will hyperlink to in the KPI Manager application.

If there are no related reports or kpis, the related report and kpi columns will not appear as shown below
 V75_Report Feature Guide

7.3 Property Files and Cron Tasks

A top level listing of the System Properties used by Reporting is shown below
Property Setting Description Default
Value
mxe.report.birt.maxconcurrentrun Manages the number of BIRT immediate and Scheduled Reports 5
that can be run concurrently
Used for Performance Maintenance

mxe.report.birt.queueidletimeseconds Frequency that the Queue Manager polls the Queue for new report 60
jobs
Used for Performance Maintenance

mxe.report.birt.disable.queuemanager Defines whether the queue manager is enabled. If the queue 0

manager is disabled (value set to 1) scheduled reports will not be
executed on the server.
Used for Multi-Server Configurations,
Performance Maintenance

mxe.report.birt.viewerurl BIRT Viewer URL for cluster or separate report server, ex:
http://myhost:myport/maximo/report
Used for BIRT Report Only Server (BROS)
Configuration
mxe.sessiontoken.timeoutseconds Token based session timeout in seconds. This token is used in the 180 seconds or
authentication of the user to the Report Server. 3 minutes
Used for BIRT Report Only Server (BROS) Note: the session token timeout setting code is generic and
Configuration currently only BIRT Reporting uses this functionality.
mxe.Reportsinapage Defines the number of reports to display in the Report Window 5
mxe.report.adhoc.editWithGroupAccess Enables editing of Ad Hoc report when any security group has 0 (No)
access to the report.
For QBR (Ad Hoc) Reporting
For example, if an Ad Hoc report is created with Public security
Access
-If the setting is No, the creator of the ad hoc report cannot edit it

-If the setting is Yes, the creator of the ad hoc report can edit it
mxe.report.adhoc.prevewLimit Introduced in Version 7.5.0.3 Fixpack April 2013, enables you to 50
For QBR (Ad Hoc) Reporting define the maximum record limit value during QBR report Creation

Other Related Property Settings

mxe.email.content.type Sent the content type for all communications Text/html
Impacts display of email text received from the Comment section
of the report request page. If you want text to be delivered with
carriage returns, set value to text/plain.

Reference Blog: http://ibm.co/JOKHEr

123
 7.3.1 Key Report Property Settings – Direct Print, Direct Print with Attachments
Property Setting Description Default
Value
mxe.activex Determines if ActiveX Controls can be used for Direct Print (DP) Yes
and Direct Print with Attachments (DPA)
mxe.directprint.inherited.attachment Defines if inherited docs should be enabled for printing with Direct No
Print with Attachments Functionality

mxe.doclink.defaultPrintDocWithReport Default value of printing attached document with report if printable Yes
type
mxe.report.AttachDoc.validateURL Property to determine if the URL of the attached document should Yes
be validated before printing from the V7 Server.

mxe.directprint.javaconsole.debug Enable output to Java Console for troubleshooting of Direct Print, No

Direct Print with Attachments
mxe.directprint.printtime.wait Maximum duration in seconds the current print process waits 600
before moving to the next process
Notes: 1. This setting is applicable only to reports, and any PDF
Attachments. 2. Prior to the V7.5.0.3 release, this value must be set
via the Database, not the System Property Application
mxe.report.birt.PrintSeparateRecord Enables printing of each record separately when no attachments No
are in the record set.
Other Related Property Settings
mxe.doclink.securedAttachment Identifies if the attachment is secured or not False

If you set this value to true, and you want to print

attachments which are Microsoft Office attachments,
additional configuration may be required depending on the
release you are using. See the Direct Print guide referenced
below for additional details.

Additional details on these property settings for Direct Print and Direct Print with Attachments can be
found in the V75 Report Application Toolbar Access Direct Print Guide. You can access this guide here:
http://ibm.co/KgsJfp or via the Report Reference Materials Page here: http://ibm.co/14r8jK7
 V75_Report Feature Guide

7.3.2 JVM System Properties

Property Setting Description
mxe.report.birt.tempfolder Specifies location of temporary folder on the Server for BIRT Runtime and temporary
files created during the report execution process.

*Note: Do not include any spaces in the directory path for this temporary folder.

The setup of this property varies for Websphere or Weblogic. Reference the System
Administrators Guide for more details on enabling JVM System Properties.
io.tmpdir The IO Temp directory is used for intermittent, individual BIRT report file generation.
This temp directory is deleted when the report completes execution.

For details on specifying it in Websphere, see below.

To set the report temp directory (mxe.report.birt.tempfolder) in Websphere:

1. Login to Websphere Integrated Service Console

2. Go to servers -> Application servers

3. From the right panel click on the server where you have deployed maximo.

4. Under "Server Infrastructure" click on "Process Definition".

5. Under "Additional Properties" click on "Java Virtual Machine"

6. Add the following to the generic JVM Argument Dmxe.report.birt.tempfolder=c:\tempReport\BIRT-

TEMP

Where you specify the directory of your choice without any spaces

7. Save and restart the server.

To set the IO temp directory, follow the same procedure above, and add the following to Generic JVM
Argument

-Djava.io.tmpdir= c:\tempReport\BIRT-TEMP-IO

Where you specify the directory of your choice without any spaces

125
 7.4 Cron Tasks
Cron Task Description
REPORTSCHEDULE Used for Scheduling of BIRT Reports. *NOTE: Its Access Level is set to READONLY.
Administrators should monitor report schedules via the Report Administration
application.

REPORTLOCKRELEASE Monitors the locks on report jobs

REPORTUSAGECLEANUP Determines frequency that entries in REPORTUSAGELOG Table are deleted

REPORTOUTPUTCLEANUP Determines frequency that scheduled report outputs in the Report Viewer application are
deleted

REPORTADHOCLOCINST Determines the frequency that newly created Ad Hoc Report Request Pages are enabled
in multi-language environments. (Introduced in 7.5.0.1)

When a public QBR is saved in a multi-language environment, the SYNCREPORTLABELS

maxvar is set to true. The REPORTADHOCLOC cron task will check the flag and when
true, will launch the process to synchronize the labels. After completion, it will set the
maxvar flag back to false.

*Note: This is for multi-language environments only. If you using a single language
environment, this cron task can remain inactive.
V75_Report Feature Guide

7.5 Functionality not Supported

The following is a listing of functionality not supported.

1. Ability to run a report immediately and email the report at the same time.
• If a user wants to email a BIRT Report, it must be scheduled.
• If they want to run a report and retain a copy, the report can be downloaded to .csv or
.pdf and a local copy can then be made.

2. Report Browser Back Button

The Report Browser Back Button is not supported.
This is best described by the use case below.
A user executes three reports in the same browser session. When the third report is displayed, he
can not use the arrow buttons to go back to the first or second report.
• This is because the executed reports are stored as temporary files on the application
server, and the file paths are not retained. The user may be able to go back – but the
functionality is NOT supported – as reports will not consistently display.

127
 REFERENCE MATERIALS
To access additional Maximo Report Reference materials, access this IBM Maximo Wiki Page:

https://www.ibm.com/developerworks/mydeveloperworks/wikis/home?lang=en#/wiki/IBM%20
Maximo%20Asset%20Management/page/Reporting%20Documentation

or its shortened url of http://ibm.co/1321CuI

This page contains the latest listing of report reference materials, including description, revision
levels and hyperlinks to the documentation

Additional details on Maximo Reporting can be found throughout the Wiki Pages here

https://www.ibm.com/developerworks/mydeveloperworks/wikis/home?lang=en#/wiki/IBM%20
Maximo%20Asset%20Management/page/Reporting

or its shortened url of

http://ibm.co/VgncuK
V75_Report Feature Guide

© Copyright IBM Corporation 2012

IBM United States of America
Produced in the United States of America
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM
representative for information on the products and services currently available in your area. Any reference to an IBM product,
program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally
equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is
the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this
document does not grant you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent
with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PAPER “AS IS” WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied
warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes may be made periodically to the information
herein; these changes may be incorporated in subsequent versions of the paper. IBM may make improvements and/or changes in the
product(s) and/or the program(s) described in this paper at any time without notice.

Any references in this document to non-IBM Web sites are provided for convenience only and do not in any manner serve as an
endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those
Web sites is at your own risk.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this
document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation
4205 South Miami Boulevard
Research Triangle Park, NC 27709 U.S.A.

All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and
objectives only.

This information is for planning purposes only. The information herein is subject to change before the products described become
available.

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

129
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the
United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this
information with a trademark symbol (® or ™), these symbols indicate U.S. registered or common law trademarks owned by IBM at
the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A
current list of IBM trademarks is available on the web at "Copyright and trademark information" at
http://www.ibm.com/legal/copytrade.shtml.
Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems
Incorporated in the United States, and/or other countries.

IT Infrastructure Library is a registered trademark of the Central Computer and Telecommunications Agency which is now part
of the Office of Government Commerce.

Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium,
and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other
countries.

Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other
countries, or both.

ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered
in the U.S. Patent and Trademark Office.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.

Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the United States, other countries, or both and is
used under license therefrom.

Linear Tape-Open, LTO, the LTO Logo, Ultrium, and the Ultrium logo are trademarks of HP, IBM Corp. and Quantum in the U.S.
and other countries.

Other company, product, or service names may be trademarks or service marks of others.