BIRT for Tivoli Process Automation Engine

Implementation Guidelines
By Bradley K. Downing, MBA
Version 1.5
Copyright Notice
Copyright IBM Corporation 2010. All rights reserved. May only be used pursuant
to a Tivoli Systems Software License Agreement, an IBM Software License
Agreement, or Addendum for Tivoli Products to IBM Customer or License
Agreement. No part of this publication may be reproduced, transmitted,
transcribed, stored in a retrieval system, or translated into any computer
language, in any form or by any means, electronic, mechanical, magnetic,
optical, chemical, manual, or otherwise, without prior written permission of
IBM Corporation. IBM Corporation grants you limited permission to make hardcopy
or other reproductions of any m achine-readable documentation for your own use,
provided that each such reproduction shall carry the IBM Corporation copyright
notice. No other rights under copyright are granted without prior written
permission of IBM Corporation. The document is not inte nded for production and
is furnished “as is” without warranty of any kind. All warranties on this
document are hereby disclaimed, including the warranties of merchantability and
fitness for a particular purpose.
U.S. Government Users Restricted Rights -- Use, duplication or disclosure
restricted by GSA ADP Schedule Contract with IBM Corporation.

Trademarks
IBM, the IBM logo, Tivoli, the Tivoli logo, AIX, Cross -Site, NetView, OS/2,
Planet Tivoli, RS/6000, Tivoli Certified, Tivoli Enterprise, Tivoli Enterpri se
Console, Tivoli Ready, and TME are trademarks or registered trademarks of
International Business Machines Corporation or Tivoli Systems Inc. in the
United States, other countries, or both.
Lotus is a registered trademark of Lotus Development Corporation .
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
C-bus is a trademark o f Corollary, Inc. in the United States, other countries,
or both.
PC Direct is a trademark of Ziff Communications Company in the United States,
other countries, or both and is used by IBM Corporation under license.
ActionMedia, LANDesk, MMX, Pentium, and P roShare are trademarks of Intel
Corporation in the United States, other countries, or both. For a complete list
of Intel trademarks, see http://www.intel.com/sites/corporate/trademarx.htm.
SET and the SET Logo are trademarks owned by SET Secure Electronic Transaction
LLC. For further information, see http://www.setco.org/aboutmark.html.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and other countries.
Other company, product, and service names may be trademarks or service marks of
others.

Notices
References in this publication to Tivoli Systems or IBM products, programs, or
services do not imply that they will be available in all countries in which
Tivoli Systems or IBM op erates. Any reference to these products, programs, or
services is not intended to imply that only Tivoli Systems or IBM products,
programs, or services can be used. Subject to valid intellectual property or
other legally protectable right of Tivoli Systems or IBM, any functionally
equivalent product, program, or service can be used instead of the referenced
product, program, or service. The evaluation and verification of operation in
conjunction with other products, except those expressly designated by Tivo li
Systems or IBM, are the responsibility of the user. Tivoli Systems or IBM may
have patents or pending patent applications covering subject matter in this
document. The furnishing of this document does not give you any license to
these patents. You can s end license inquiries, in writing, to the IBM Director
of Licensing, IBM Corporation, North Castle Drive, Armonk, New York 10504 -1785,

iii
U.S.A.

iv
Acknowledgements

Pam Denny – for providing the bulk of the material and answers to seemingly endless question s
by the editor.

v
About the Tivoli Field Guides
Sponsor
Tivoli Customer Support sponsors the Tivoli Field Guide program.

Authors
Those who write field guides belong to one of these three groups:

 Tivoli Support and Services Engineers who work directly wi th customers

 Tivoli Customers and Business Partners who have experience using Tivoli software in a
production environment
 Tivoli developers, testers, and architects

Audience
The field guides are written for all customers, both new and existing. They are ap plicable to
external audiences including executives, project leads, technical leads, team members, and to
internal audiences as well.

Types of Field Guides

Two types of Tivoli Field Guides describe how Tivoli products work and how they are used in real
life situations:

 Field Guides for technical issues are designed to address specific technical scenarios or
concepts that are often complex to implement or difficult to understand, for example:
endpoint mobility, migration, and heartbeat monitoring.
 Field Guides for business issues are designed to address specific business practices that
have a high impact on the success or failure of an ESM project, for example: change
management, asset Management, and deployment phases.

Purposes
The Field Guide program has tw o major purposes:

 To empower customers & business partners to succeed with Tivoli software by

documenting and sharing product information that provides accurate and timely
information on Tivoli products and the business issues that impact an enterprise sy stems
management project
 To leverage the internal knowledge within Tivoli Customer Support and Services and the
external knowledge of Tivoli customers and Business Partners

Availability
All completed field guides are available free to registered customers and internal IBM employees
at the following Web site:

http://www.ibm.com/software/sysmgmt/products/support/Field_Guides.html

Authors can submit proposals and access p apers by e-mail:

vii
mailto:[email protected]

viii
Table of Contents

IMPLEMENTATION GUIDE LINES............................................................. I

Sponsor................................ ................................ ................................ ...vii
Authors ................................ ................................ ................................ ...vii
Audience ................................ ................................ ................................ .vii
Types of Field Guides ................................ ................................ ............ vii
Purposes................................ ................................ ................................ .vii
Availability ................................ ................................ .............................. vii

IMPLEMENTATION GUIDE LINES.......................................................... 13

INSTALLING BIRT INTO IBM’S TIVOLI PROCESS AUTOMATION

ENGINE V7 FRAMEWORK ....................................................................... 13
BIRT TOOL SETUP REQUIREMENTS ............................................................................... 13
IBM Employees................................ ................................ ............................ 13
Non-IBM Employees ................................ ................................ .................... 16
INSTALLING V7 DESIGN FILES FOR BIRT ...................................................................... 20
ACCESSING THE BIRT DESIGNER .................................................................................. 22
CONFIGURING BIRT REPORT DESIGNER TO WORK WITH V7 CONFIGURATION FILES .... 27

WORKING WITH MAXIMO REPORTS ................................................... 30

MAXIMO STANDARD REPORTS INTERFACE .................................................................... 30
WOTRACK ................................ ................................ ................................ ..30
The open method ................................ ................................ ................... 32
The Fetch Method ................................ ................................ .................. 33
The Initialize Method ................................ ................................ .............. 33
WOPRINT................................ ................................ ................................ ....34
INVENTORY_ROP and INVENTORY_ROP_UPDATE ............................... 35
The ROP Initialize Method ................................ ................................ .....35
The UPDATE Initialize Method ................................ .............................. 35
The ROP Open Method ................................ ................................ ..........37

ix
 The ROP Fetch Method ................................ ................................ ..........39
LOCALIZATION SETUP .................................................................................................... 41
How Localization is Enabled ................................ ................................ ........42
How Report Labels get Localized ................................ ................................ 43
Request Pages ................................ ................................ ............................ 45
Static Content ................................ ................................ ......................... 46
Dynamic Content ................................ ................................ .................... 46
Common Customer Scenarios ................................ ................................ .....47

REPORT MODIFICATION ......................................................................... 48

REPORT TYPES ............................................................................................................... 48
List ................................ ................................ ................................ ............... 48
Sub-Report................................ ................................ ................................ ...51
Grouped................................ ................................ ................................ .......54

SUMMARY OF CUSTOM RE PORT FUNCTIONS .................................. 55

MAXIMO REPORT METHODS .......................................................................................... 55
MXReportSqlFormat.class M ethods ................................ ............................ 56
createParamWhereClause(String columnName, String paramValue) 56
getCombinedDateAndTime(Date date, Date time) ............................... 56
getCurrentDateFunction() ................................ ................................ ......56
getCurrentTimestampFunction() ................................ ........................... 56
getDouble(string)................................ ................................ .................... 57
getEndDayTimestamp(Date d) ................................ ............................... 57
getEndDayTimestampFunction(Date d) ................................ ................ 57
getStartDayTimestamp(Date d) ................................ .............................. 57
getTimestampFunction(Date d) ................................ ............................. 57
MXReportDataSetProvider.create(String dataSourceName, String
dataSetName) ................................ ................................ .............................. 57
MXReportTxnProvider.create(“maximoDataSource”); ................................ ..58

SAMPLE USAGE OF METHODS.............................................................. 58

EXAMPLE REPORT METHODS ......................................................................................... 58
beforeOpen Method ................................ ................................ ..................... 58
Open Method ................................ ................................ ............................... 58

x
 Fetch Method ................................ ................................ ............................... 59
beforeClose Method ................................ ................................ .................... 61
OTHER METHODS ........................................................................................................... 63
Initialize Method ................................ ................................ ........................... 63
afterFactory................................ ................................ ................................ ..64
User Functions (in any method) ................................ ................................ ...64

REPORTING BEST PRACTICES............................................................... 65

LOOK AND FEEL ............................................................................................................. 65
MaximoSystemLibrary.rptlibrary ................................ ................................ ..65
STANDARDIZED FUNCTIONALITY ................................................................................... 65
Common Methods and Techniques ................................ ............................. 65
UNDERSTANDING TPAE INTEGRATION .......................................................................... 65
Review of Common Method Overrides or “Plagiarism for Productivity” .......65

xi
BIRT for Tivoli Process Automation Engine (Maximo)
7.x
Implementation Guidelines

The purpose of this guide is to enable the Maximo develope r to install and modify existing report source code
using the BIRT tool in the Eclipse framework. This guide is not intended to replace any existing documentation.
Rather, it is intended to supplement that documentation and re -enforce critical points in that documentation.
Further, this guide is not intended as educational material per -se, but rather as insight into the implementation
and practice of using the BIRT tool in the Maximo framework only.

The author strongly suggests that the practitioner obtain formal training from IBM (IBM Tivoli Reporting for
Enterprise IT and Asset Management 7.1) before using this guide in depth.

1
Installing BIRT into IBM’s Tivoli Process Automation
Engine v7 framework
Installing BIRT in and of itself is not a difficult task. However, there are considerations that the implementation
team MUST take into account in order to mitigate risk to the installation of the software.

BIRT Tool Setup Requirements

IBM Employees
Download and install Eclipse SDK and BIRT from the IES website.

1. Maximo V7 (7.1.1.1 through 7.1.1.4) uses Eclipse 3.2 with BIRT Designer 2.1.2 . The following
components require installation:

a. Eclipse SDK 3.2.2

b. GEF SDK

c. EMF (Core) SDK

d. Business Intelligence Reporting Tools SDK

e. JDK 1.5

f. iText Jar (Optional)

2. Maximo V7.1.1.5 uses Eclipse 3.4.2 with BIRT Designer 2.3.2 with the same components.

a. Eclipse SDK 3.4.2

b. The full install package for BIRT 2.3.2 is located here:

13
 http://www-01.ibm.com/software/brandcatalog/portal/opal/details?NavCode=1TW10OT07

c. In order to upgrade rather than install please navigate to this support document for complete
instructions:
http://www-01.ibm.com/software/sysmgmt/products/support/IBMMaximoAssetManagement.html

3. In order to obtain the software , use the following steps. IBM Employees must downloa d these
components from the IES Website.

a. Create a local directory to store Eclipse and BIRT. The example shown here uses a local
directory of ‘eclipse_download’. NOTE: The local folder should NOT have any spaces in its
path.

b. Access http://ies.ottawa.ibm.com/iss/ies/downloads/index.php

c. Click on 3.2.2 Build, Win 32. Under the Eclipse Full Structure, locate the Eclipse Full SDK and
save the file to your directory.

14
d. On the same page, locate the Business Intelligence and Reporting Tools SDK and save the
file to your local directory.

e. Locate the EMF (Core) SDK and save the file to your local directory.

f. Locate the GEF SDK and save the file to your local directory.

g. Extract the Eclipse Zip File first to your local directory. Once complete, extract

15
 the remaining three zip files to your local folder. If you receive prompts to replace existing fi les,
only replace if the date is greater than the existing file. Once complete, your directory should look
like the following:

h. If JDK 1.5 (5.0) is not already installed, then an IBM -authorized version is available from “jim”:

http://w3.hursley.ibm.com/java/jim/jim/index.html

For Windows, the current download is here (subject to change):

http://w3.hursley.ibm.com/java/jim/ibmsdks/latest/windowsia32/50servicerelease4windowsia32pw
i32dev20070201j9/index.html

Non-IBM Employees
a. Navigate to the following website: http://www-01.ibm.com/software/brandcatalog/portal/opal
Login with your IBM ID and then search for BIRT .

b. Click on the icon and then click on the BIRT ReportDesigner v2.1.2 link.

16
c. When the following page appears, click on the button.

d. You will be prompted to log in to the site again.

17
 e. Enter your IBM credentials again.

The next page will show your IBM login credentials and prompt you to answer some questions . You will also be
required to check a License agreement checkbox.

18
f. Now Click on “I confirm”

g. Click on the check box and then click on Download Now.

19
Once the download process is complete, move the zip file to the location of the machine that has a local copy
of Maximo V7, with the report source.

Note: This is required in order to perform the next steps.

Installing V7 Design Files for BIRT

A local copy of Maximo V7, with the report source, is required in order to perform the next steps. Additionally, in
the file paths below, v20070205 -1728 is a version number and may be slightly different depending on the
Eclipse SDK version installed.

1. Locate the compiled classes for report scripting

2. Navigate to the location below :

\\eclipse\plugins\org.eclipse.birt.report.viewer_2.1.2.v20070205-1728\birt\WEB-INF

a. Create a class folder

b. Copy the entire \com folder from step1 to

\\eclipse\plugins\org.eclipse.birt.report.viewer_2.1.2.v20070205-1728\birt\WEB-INF\classes

3. Copy mxdatasources.properties using the same source and destination folders from steps 1 and 2.

20
 4. Open the copied mxdatasources.properties file and edit it for the local configuration

a. Set the URL, driver, username, password, and schemaowner properties for the local
environment following the sample formats provided.

b. Change #<DataSourceName> to maximDataSource

5. Finally, in order to view reports in a PDF forma t within the BIRT Designer, the practitioner will need to
copy the iText.Jar file from the Maximo build folder to the local installation folder of Eclipse.

a. First, locate the iText.Jar file, which is called com.lowagie.itext_1.5.2.jar. It is located in

\\<maximo>\applications\maximo\maximouiweb\webmodule\WEB-INF\birt\platform\plugins

b. Copy this file to <eclipse download>eclipse \plugins

NOTES

1. The mxdatasources.properties file is only required by the report designer at runtime ; the connection
information will be set from Maximo.

2. A sample of this file for DB2 is shown below:

#<DataSourceName>.<propertyName>=valu e
# driver for ORACLE
# oracle.jdbc.driver.OracleDrive r
# sample url for ORACLE
# jdbc:oracle:thin:@<HOST>:<PORT>:<SID >
# driver for SQLServer
# com.inet.tds.TdsDriver
# sample url for SQLServer
#
jdbc:inetdae7a:hostname:port?database=dbname&langu age=us_english&nowar n
ings=true
# driver for DB2
# com.ibm.db2.jcc.DB2Drive r
# sample url for DB2
# jdbc:db2://localhost:50000/dbalia s

maximoDataSource .url=jdbc:db2://MAXIMODB2:50000/MAXIMO
maximoDataSource .driver=com.ibm.db2.jcc.DB2Drive r
maximoDataSource .username=maximo

21
 maximoDataSource .password=maximo

The values in red point to a sample local database. You can check yours and other s that are available for you
to choose from Start Menu \Programs\IBM DB2\Set-up Tools\Configuration Assistant.

The key name in blue is the default set for all reports; this text must be used exactly in order for the reports to
work properly.

3. Copy the JDBC driver(s) from the fol der: \\<Maximo>\applications\maximo\lib into

\\eclipse\plugins\org.eclipse.birt.report.viewer_2.1.1.v20070205-1728\birt\WEB-INF\lib

These drivers are only used by the designer .

Note: For Oracle, use oraclethin.zip

For SQL Server, use opta.jar

For DB2, use db2jcc.jar and db2jcc_license_cu.jar

Further, if the practitioner experiences any “NoClassDef Found” errors, experiment with extracting the jar files
into the “classes” folder, which was created in step 2.b (above).

Accessing the BIRT Designer

1. Create a shortcut to eclipse.exe. Be sure to include the correct path pointing to the local JDK 1.5 in stall
folder. An example is highlighted in red in the target for the shortcut.

{DRIVE}:\\eclipse_download\BIRT\eclipse\eclipse.exe -vm "{DRIVE_designation}:\program

files\IBM\Java50\bin\javaw.exe" -vmargs -Xmx512m

22
2. Select a workspace location. Check “Use this as default” field and OK.

3. Eclipse SDK will open (see image below) .

23
4. From the menu, select File – New – Project. Scroll down to the Business Intelligence and Reporting
Tools Location, and select Report Project. Click Next.

24
5. Type in a project name and click Finish.

25
6. The BIRT Report designer within Eclipse SDK Displays.

26
Configuring BIRT Report Designer to Work with V7
Configuration Files
NOTE: Use forward slashes or the Select button when specifying the folder paths in Eclipse.

1. Specify the resource folder location to import the V7 Libraries.

a. From the Menu, select Windows – Preferences.

b. Expand Report Design and select Resource.

c. Browse to the local report library location and select Apply.

//<maximo>/reports/birt/libraries

2. Specify the templates folder location to import the V7 Templates.

a. If the dialog box is not already o pen (below), then select from the menu, “Window |
Preferences.”

b. Expand Report Design and select Templates

27
 c. Browse to your local report template location and select Apply.

<maximo>/reports/birt/templates

3. Disable the Comment Template

a. If the dialog box is not already open (below), then select from the menu, “Windows |
Preferences.”

b. Navigate to the Report Design | Comment Template preference.

c. Remove the flag from the “Generate comment when creating a report design” field if it is set.

28
4. Next, import the report project. This will import the V7 Reports into the project workspace.

a. From the menu, select File – Import.

b. Expand the General folder and select Existing Projects into Workspace.

c. Click Next.

d. Browse to your local report subfolder location:

\\<maximo>\reports\birt\reports

5. Click OK.

29
 6. Click Finish.

2
Working with Maximo Reports
Maximo reports are unique in their setup and configuration within the Eclipse/BIRT toolset. This section
describes common report features and discusses the most commonly used methods for business logic
implementation. This is not intended to be an exhaustive study but rather a primer on where to find common
and reusable code that the practitioner can modify to meet unique requirements.

Maximo Standard Reports Interface

WOTRACK
This screen shot is of the WOTRACK report, in the Eclipse Developer Interface using the BIRT plugin.

30
This report is based on the WORKORDER table and works with the Work Order Tracking ap plications (i.e.
WOTRACK, QUICKREP, CHANGE, ACTIVITY, and RELEASE). This report has several methods overridden.

The first two methods to study are located on the Data Set component. Focus on the data set that requires
attention:

1. Click on the desired data set in either the Data Ex plorer tab or the Outline View t ab. By default, both are
located on the left-hand side of the screen.

31
2. Click on the Script Tab in the Layout pane.

3. Select the desired method from the drop -down menu.

The open method

This method defines the interrogative that BIRT passes to the database in order to define the report’s initial
selection.

32
The Fetch Method

This method allows the developer to define the various row elements to display. It is critical to note t he correct
data type. The Database Data Type and the BIRT Data Type are often different, which means that the
definition of the correct “get” method is highly prone to errors in report generation. To get the correct mapping
of the types to one another, please refer to the Report Developer Guide. This information is available on the
following website:

http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/index.jsp?topic=/com.ibm.itmaxam.doc/welcome.htm

The Initialize Method

Unlike the first two methods located on the Data Set, the initialize method is located on the main report design
component. Using the Outline tab , select the xxxx.reportdesign component at the top of the Out line.

Ensure that the Script tab is in Focus and that the initialize method is available for editing.

33
Developers use this method for many purposes, but the most common is for debugging. Using the above code
enables the developer to view a log file tha t delivers significant information , such that the practitioner may
identify and fix errors easily.

Note:The initial line performs an import package. This package enables the report to access and use the
various custom Maximo methods developed by IBM. Witho ut this package, the reports will not perform
according to expected standards within the Maximo framework.

Every report built for the TPAE (Maximo) framework will have these methods overridden.

WOPRINT
The next report that has interesting meth ods to study is the Work Order Details R eport. In the Fetch method,
the Long description is fetched using a data set open method.

This series of JavaScript snippets allows the user to obtain the long description for each work order retrieved in
the main data set “open” method. Since this dataset open method is embedded on the Fetch method of the
main data set, it will retrieve the long description for each record in the data set.

34
With this approach, the long description for each task on the work order (or job plan) ca n be retrieved simply by
copying the function to the fetch method of the task data set.

INVENTORY_ROP and INVENTORY_ROP_UPDATE

The inventory ROP report provides the users of the Maximo Asset Management suite a standardized method
for keeping the Reorder P oint of the Maintenance and Repair Operation (MRO) Inventory up -to-date based on
usage.

The ROP Initialize Method

This method sets two variables to enable the update report to work. These variables are used to track the
update time.

importPackage(Packages. com.ibm.tivoli.maximo.repor t.script);

mxReportScriptContex t = MXReportScriptContext.init ialize(reportContext) ;

//mxReportScriptContext.setDefaultLogLevel("DEBUG" );
//mxReportScriptContext.setDefaultLogFile("C:/temp /inventory_rop.log") ;
scriptLogger = mxReportScriptContext.getReportScri ptLogger();

var timeInMs = Date.now();

attkey = "st-inventory_rop_" + params["appname"]+ "_"+ timeInMs;

dskey = "ds-inventory_rop_" + params["appname"]+ "_"+ timeInMs;

The UPDATE Initialize Method

The report starts with a n override of the Initialize method , which determines whether the update statement will
be executed during the processing of the report.

importPackage(Packages.com.ibm.tivoli.maximo.report.script);
mxReportScriptContext = MXReportScriptContext.initialize(r eportContext);

//mxReportScriptContext.setDefaultLogLevel("DEBUG");
//mxReportScriptContext.setDefaultLogFile("C:/temp/inventory_rop_update.log");

scriptLogger = mxReportScriptContext.getReportScriptLogger();

var status = new String("unverifiable");

if(params["paramstring"].value && params["paramdelimiter"].value) {

var paramlist=params["paramstring"].split(params["paramdelimiter"]);

if (scriptLogger.isDebugEnabled()) {
scriptLogger.debug(" >>> paramlist array : " + paramlist.join());
}

if(paramlist.length == 2) {
var attkey=paramlist[0];
var dskey=paramlist[1];

try{

var updStmtList = mxReportScriptContext.getHttpSessionAttribute(attkey);

var dsName = mxReportScriptContext.getHttpSessionAttribute(dskey);

if (scriptLogger.isDebugEnabled()) {
scriptLogger.debug(" >>> updStmtList : " + updStmtList.length);
}

35
 if(updStmtList!=null){
var updTxn = MXReportTxnProvider.create(dsName);
for(var i=0; i < updStmtList.length; i++) {
updStmtList.length); var updStmt = updTxn.createStatement();
updStmt.setQuery(updStmtList[i]);
if (scriptLogger.isDebugEnabled()) {
scriptLogger.debug(" >>> updStmt #" + (i+1) + " of " +
}

36
 }
if (scriptLogger.isInfoEnabled()) {
scriptLogger.info(" >>> updTxn ready to be saved" );
}

updTxn.save();
status = "update_success";
if (scriptLogger.isInfoEnabled()) {
scriptLogger.info(" >>> updTxn success");
}
}
}
catch( e ){
status = "update_error";
if (scriptLogger.isInfoEnabled()) {
scriptLogger.info(" >>> updTxn failed");
}
}
finally{
updTxn = null;
mxReportScriptContext.removeH ttpSessionAttribute(params[ "paramstring"]);
}
}
}

Additionally, when debugging is turned on, the code displays the update statements being processed.

The ROP Open Method

In this method, the session context allows the interaction of the update report to ca ll the ROP calculation with
the appKey and dsKey parameters. Subsequently , the “where” clause is built dynamically based on the user’s
input. The Lead Time in months is set based on the Start Date entered by the user. Due to differences in
database syntax restrictions, the total items clause is structured accordingly. Finally, the SQL is properly
constructed and passed to the database.

maximoDataSet = MXReportDataSetProvider.create (this.getDataSource().getName() ,

this.getName());
maximoDataSet.open() ;

var request = reportContext.getHttpServletRequest() ;

if(request != null){
var session = request.getSession() ;
session.setAttribute(dskey , this.getDataSource().getName()) ;
}

params["paramdelimiter"] = "||";
params["paramstring"] = attkey + params["paramdelimiter"] + dskey;

var sqlText = new String();

if((BirtComp.notEqual(params[ "location"],null))&&(BirtComp.notEqual(params[ "loca

tion"],''))) {
params["where"]+= " and " +
MXReportSqlFormat.createParamWhereClause( "inventory.location" ,
params["location"]);
}
if((BirtComp.notEqual(params[ "site"],null))&&(BirtComp.notEqual(params[ "site"],'
'))) {
params["where"]+= " and " +
MXReportSqlFormat.createParamWhereClause( "inventory.siteid" , params["site"]);
}

lTimeMonthsClaus e = " floor("

+ DateTimeSpan.months(params[ "startdate"], new Date()) + ") as
leadtimemonths, ";

37
if(maximoDataSet.isDB2() )
totalItemsClause = "( select max(a) from (select count(*) as a from
matrectrans "
+ " where issuetype='TRANSFER ' union select count(*) as a from matusetrans
where "
+ " issuetype='ISSUE') as b) "
+ " as totalitems, ";
else
totalItemsClause = " ((select count(*) from matrectrans where

38
issuetype='TRANSFER')+( "
+ " select count(*) from matusetrans where issuetype='ISSUE')) as
totalitems, "

sqlText = "select distinct inventory.itemnum as itemnum, item.description as

description, "
+" inventory.orderuni t as orderunit, inventory.minlevel as minlevel,
inventory.deliverytim e as delivery,"
+" inventory.sstock as sstock, " + lTimeMonthsClause + " inventory.itemseti d as
itemsetid,"
+ totalItemsClause
+" conversion.conversio n as conversion, inventory.location as location,
inventory.siteid as siteid "
+" from item, inventory "
+" left outer join matusetrans on inventory.itemnum = matusetrans.itemnu m "
+" and inventory.itemseti d = matusetrans.itemsetid "
+" and inventory.siteid = matusetrans.sitei d "
+" and inventory.locatio n = matusetrans.storelo c "
+" left outer join "
+" matrectrans on inventory.itemnum = matrectrans.itemnum "
+" and inventory.itemseti d = matrectrans.itemseti d "
+" and inventory.siteid = matrectrans.sitei d "
+" and inventory.locatio n = matrectrans.tostorelo c "
+" left outer join conversion on inventory.itemnum= conversion.itemnu m "
+" and inventory.itemsetid=conversion.itemseti d "
+" and inventory.orderunit=conversion.frommea sureunit "
+" where " + params["where"]
+" and item.itemtype = 'ITEM'"
+" and inventory.itemnum=item.itemnum "
+" and inventory.itemsetid=item.itemseti d "
+" group by inventory.itemnum , item.description ,
inventory.orderunit,inventory.minlevel , inventory.sstock,
inventory.deliverytime , inventory.itemsetid , conversion.conversion ,
inventory.siteid , inventory.locatio n "
+" order by inventory.itemnum , item.description ,
inventory.orderunit,inventory.minlevel , inventory.sstock,
inventory.deliverytime , inventory.itemsetid, conversion.conversion ,
inventory.siteid , inventory.locatio n "
;

maximoDataSet.setQuery(sqlText) ;

The ROP Fetch Method

The report starts with an override of the Initialize method , which determines whether the update statement will
be executed during the processing of the report. Next, a number of variables are created to allow the
processing of the ROP set point. Allowing for a normalization of the number of days in any given month, the
algorithm uses conversion factors (if used) to set the safety stock, which is finally used to set the Re -Order
Point. Once the point has been calculated , if the update report, calls this report the update statements are used
to update the database with the new calculated set point.

if (!maximoDataSet.fetch() )
return (false);

// Add a line for each output column

// The specific get method should match the data type of the output column.
row["itemnum"] = maximoDataSet.getString( "itemnum");
row["description"] = maximoDataSet.getString( "description");
row["orderunit"] = maximoDataSet.getString( "orderunit");
row["minlevel"] = maximoDataSet.getFloat( "minlevel");

39
row["sstock"] = maximoDataSet.getFloat( "sstock");

var leadtime = 0;
var sstock = 0;
var newlevel = 0;

if((maximoDataSet.getInteger( "totalitems")==0)||(maximoDat aSet.getInteger( "leadt

imemonths")==0)){
leadtime=0;
sstock=0;
}
else
if(maximoDataSet.getInteger( "delivery")==0){
sstock=0;
leadtime =
maximoDataSet.getInteger( "totalitems")*maximoDataSet.getFloat( "leadtimemonths" )/
30.44;
}
else
{
leadtime =
maximoDataSet.getInteger( "totalitems")*maximoDataSet.getFloat( "leadtimemonths" )/
30.44;
sstock =
Math.pow(2*maximoDataSet.getInteger( "delivery")*(maximoDataSet.getInteger( "total
items")*maximoDataSet.getFloat( "leadtimemonths" )/30.44)/30.44,(1/1.6)) ;
}

newlevel = sstock + leadtime;

row["newrop"] = newlevel;
row["newsstock"] = sstock;

var conversion = maximoDataSet.getFloat( "conversion");

if(conversion==null)
conversion=0;

40
 row["cfactor"] = conversion;

var request = reportContext.getHttpServletRequest() ;

if(request != null) {
var session = request.getSession() ;
var updStmtList = session.getAttribute(attkey) ;

if(updStmtList==null){
updStmtList = new Array;
}

var updateQuery = "update inventory set minlevel=" + newlevel

+ " where itemsetid='" +maximoDataSet.getString("itemsetid") + "' "
+ " and siteid='" +maximoDataSet.getString( "siteid")+ "' "
+ " and itemnum='" +maximoDataSet.getString( "itemnum") + "' "
+ " and location='" +maximoDataSet.getString( "location") + "'";

updStmtList.push(updateQuery) ;

session.setAttribute(attkey , updStmtList);
}

return (true);

Localization Setup
Two specific actions are required to enable localization of V7 reports.

1. Both the Language and Locale for the user must be set.

These can be set in the User’s Default Profile Informa tion

Or in the User’s Application

2. The request pages for each of the languages required by a client need to be generated in the report
admin app for each of these different language s. This can best be described by the use case below.

41
 a. A client needs to enable V7 in English, Spanish, and Italian.

b. The report administrator’s locale is set to English. First, he would access Report Admin, and
generate the request pages xml in English.

c. Next, he would sign out. He would then sign back in and change his locale to Spanish. He
would then access Report Admin, and would generate the report request pages in Spanish.

d. Finally, he would sign out again. He would sign back in, change his locale to Italian, and
generate the report request pages in Italian.

The request pages would then be available in all three languages – English, Spanish, and Italian.

How Localization is Enabled

Once the two setup-steps described above are performed, localization is enabled.

When a user signs in to V7, his language is known. It is then compar ed to the V7 MAXVAR of
BASELANGUAGE.

 If the user’s language is the same as the MAXVAR’s base language setting, then V7 and reporting
will retrieve data from the standard Database Tables (e.g. Report labels come form REPORTLABEL).

 If the user’s language is different from the MAXVAR’s base language setting, then V7 and Reporting
will retrieve data from the corresponding localized tables (e.g. Report labels come from
L_REPORTLABEL where Language Code is equal to the Language Code of the End User).

This is shown below:

42
How Report Labels get Localized
All report labels and titles are referenced in their design file by key values. The key value s are simply unique
text values of the control. These key values will be stored in the REPOR TLABEL table in the Database.

For example, in the Report Usage Report, reportusage.rptdesign, two of its labels are circled – User and
Success.

These two label values are stored in the REPORTLABLE Table as shown below.

For clients using a language othe r then English, or for clients enabl ing multiple languages in a V7
environment, corresponding database tables identified by L_REPORTLABEL will be used. These tables will
hold the translated value(s) of the label values.

Multiple instances of a label value can be stored in the L_REPORTLABEL table for multiple languages. The
combination of the Label Value and Language Code will make the label value unique.

L_REPORTLABEL.REPORTLABELID L_REPORTLABEL.LANGCODE L_REPORTLABEL.LABELVALUE

12345 ES mi primer informe
12345 FR mon premier rapport
12346 ES fecha
12346 FR date

Labelkey and Labelvalues for each control in each report have to be defined by the Report Developer. This
occurs when the reports are being developed in BIRT’s report designer.

To do this, after the developed has completed the code for the report, but before it is ready for importing, the
developer needs to enable the labels for localization. To do this, the practitioner performs the following steps:

1. Click on the Layout Tab, Property Editor.

43
 2. Select the Localization Property.

3. If no values are displayed, click on the Browse button to locate the Resource (properties) file.

NOTE: One property file will exist for each application

4. Select the correct text value from the list of existing values.

5. If a new value is needed, type in the text for the new value and it will be saved to the PropertyFile.

This is shown below. The Work Order Label is highlighted in the Layou t Pane. Only values for ‘page’ and ‘of’
are defined, so a new value for Work Order must be a dded.

The Value of Work Order, with a key of work order , is added. This is added to the resource file.

The next report needing a Work Order Value can re -use the same key value.

44
As the values are added, the properties file is updated. A sample o f the wotrack.properties file is shown
below. The first value on the left is the label key, and the second value on the right is the label value. The
label value is the value that will be translated.

Property files are located in <maximo> \reports\birt\libraries

NOTES

A. Property files are application -specific. This means that all reports stored in the SLA Application, for
example, will use the same resource file. This enables common labels to be used by multiple reports.

B. Not every V7 App has reports. Prope rty files are only available “OOB” for those applications that have
reports.

C. If one report design file is stored in multiple applications, it only need s to use one resource file.

Request Pages
Request pages contain both static and dynamic content. Static c ontent includes text on subheaders like
Parameters and Schedule Choices. Dynamic Content includes the variable parameter text.

45
Static Content
When the dialog is generated during the Generate XML process, the MAXMESSAGE table contents are used.
Once the dialog is generated, when the dialog is shown, the MAXLABEL table is used.

NOTE: During the Generate XML process, the MAXLABEL table is populated based on the dialog XML.

For localized database, the Generate XML process would take the localized messages fro m the
L_MAXMESSAGE table and the dialog loader would populate the L_MAXLABEL with the same localized
content as in L_MAXMESSAGE table.

This means that the dialogs need to be generated from every language that we support in order to populate
the L_MAXLABEL table. When the dialog is shown, the L_MAXLABEL values are used.

NOTE: The MAXLABAL and L_MAXLABEL values are overwritten each time the Generate XML operation is
invoked.

Dynamic Content
When the dialog is generated using the Generate XML process, the REPO RTLOOKUP table contents are
used. Once the dialog is generated, when the dialog is shown, the MAXLABEL table is used.

NOTE: During the Generate XML process, the MAXLABEL table is populated based on the dialog XML.

For localized database, the Generate XML process would take the localized messages from the
L_REPORTSLOOKUP table and the dialog loader would populate the L_MAXLABEL with the same localized
content as in the L_REPORTLOOKUP table. This means that the dialogs need to be generated for every
language that we support in order to populate the L_MAXLABEL table. When the dialog is shown, the
L_MAXLABEL values are used.

46
NOTE: the MAXLABEL and L_MAXLABEL values are overwritten every time the Generate XML operation is
invoked.

Common Customer Scenarios

In this section, three Customer Setups will be reviewed. These three scenarios are

 Client 1: English Only

 Client 2: French Only

 Client 3: French Base Language – Spanish Secondary Language.

The chart below shows the process that each setup will go through to ena ble the specified languages in each
client setup.

Customer 1 Customer 2 Customer 3

Base Language English French French

Secondary Language Spanish

MAXINST Database Created English English English

Loads Localiz-able Report Tables REPORT, REPORTLABELS, REPORTLOOKUP REPORT, REPORTLABELS, REPORTLOOKUP REPORT, REPORTLABELS, REPORTLOOKUP
Because English DB, calls method, but Because English DB, calls method, but Because English DB, calls method, but
Creates Property Files nothing happens nothing happens nothing happens

Extracts XLIFF (3 Files for: REPORT,

TDT REPORTLABEL, REPORTLOOKUP)
Base Language Conversion? No Yes. Converts Base to French Yes. Converts Base to French
Loads all report data based on report.xml* Loads French Data Loads French Data
Creates L_Tables No No Yes. L_ for Spanish Values

Yes. Retain Original, create new for Yes. Retain Original, create new for
Create Properties Create report properties No French French, Spanish
jobplan.properties jobplan.properties jobplan.properties
jobplan_FR.properties jobplan_FR.properties
jobplan_SP.properties

*During startup, MX sees FR database,

Loads all Report Tables based on so does not overwrite
Start MX Server report.xml REPORT.DESCRIPTION field.
(reportdesign, reportparam…)

Miscellaneous Localization Notes

A. “Out of the Box” V7 Reports will use the following formatting for consistency:

Date: Short Format

Time: Medium Format

Date and Time: Short Format + Medium Format

BIRT offers custom date formattin g. However, due to localization issues, clients are encouraged to use only
Short, Medium, or Long Date/Time formatting for their custom reports.

B. Hyperlinks

47
If a user hyperlinks from one BIRT r eport to another, no additional code is required for localizatio n. The
language code is passed through internal report context and is not passed as part of the hyerlink.

Whether the report is a regular report or a hyperlink report, the report has to go through a single servlet that
knows about the already logged in use r and the user’s locale/languagecode/timezone information. This
information is automatically passed to the BIRT engine or to our scripting code through a framework provided
report context.

C. Fonts

Within the Labels Tab of Report Administration, there is a se ction where the Administrator can specify the
Font Name and Font Size. This functi onality does not apply to BIRT r eports.

If a client wants to change the font of the BIRT r eports to a Unicode or other format, he would change the
Style Sheet used in the Rep ort Library.

The default fonts used in the OOB reports are Arial, Helvetica, Sans -serif.

The font used will depend on what is available on the user’s browser. It will start with Arial ; if that is not
available, it will use Helvetica.

3
Report Modification
Modification of Out-of-the-Box (OOTB) reports is a common practice, and knowledge of how to make these
modifications without breaking the report is critical. Understanding how the reports are structured is critical to
the successful modification effort. F urther knowledge of specialized areas of the report, such as business
logic, plays a key role in successful modification of the report, as well. This section will cover the most
common aspects to modification. The following section will cover advanced conc epts that will aid the
practitioner in the further development and modification of BIRT reports in Maximo.

Report Types
List
The list report is the simplest form of report , and modification of this type of report usually encompasses
adding or deleting columns of data. The sample below is the WOTRACK report:

48
This list of work orders displays several columns of data for each work order. To add columns to this, you
must follow four simple steps. (Details of these steps begin on the next page).

Beginning with the layout view, one can see that there are many columns with components in each of those
columns.

This is a table format for this specific report. The template for the list report starts with a simple table. The
following steps can be used to modify t his report:

49
 1. Modify the SQL in the Open Method t o add the new attribute.

Take care to ensure that the Java Script syntax is adhered to in order to avoid introducing an error into the
report.

2. Modify the Fetch method to add the new attribute.

It is important to review the table on page 16 of the Tivoli Report Developer Guide to ensure that the correct
method is used for the correct data type. The following URL will allow the practioner to access this guide.

http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/index.jsp?topic=/com.ibm.itmaxam.doc/welcome.htm

3. Modify the Output columns on the Data set.

50
Focus on the Data set either in the Data Sets tab or in the Outline view. D ouble click on the dataset or choose
Edit from the Right Click menu. The following dialog box will appear:

Go to the last row and type in (or copy from a text editor) the name of the tab. It must match the name as
defined in the fetch method. In addition, the correct data type is required in the last row.

4. Insert a new column to the table and add the new attribute.

Focus on the column that is immediately to the right or left of the area on the report you wish to display the
new data. Right Click and then choose Insert.

If the column is in the middle of the report, there is now problem with choosing either “Column to the Right” or
“Column to the Left”. However, if the data is to be placed at the extreme right of the report (either last or next
to last), please try to use only “Column to the Left.” When the practitioner chooses “Column to the Right,” it
may cause the table to go off the end of the page.

After the column is placed on the report, then the developer can simply drag and drop the newly -created
attribute from the data set onto the desired location in the report.

Sub-Report
Examples of a sub-report type are the Detail reports, such as JOBPLAN, WOPRINT, PO, or PR. These
reports have complex data structures that form the total Job Plan or Work Order, etc.

51
 In this example, the Job Plan details report displays the various sub -
components, such as Labor, Materials, Tasks, Service, to the Job Plan.

As shown here, the various tables in the report appear in the detail row.

Notice that this is a single row for all of the sub -reports. Each sub-report relates to a particular data set. This
is called Table Binding.

When the developer focuses on the Table in the Outline view, the layout pane displays the associated
components. When the developer move s the focus to the Binding Tab on the Property Editor, the specifics of
the table binding are displayed. For each table, the developer establishes which data set is bound to that

52
table. The tables are executed in descending order, from top to bottom. This is more readily displayed in the
layout view, as shown on the previous page.

NOTE: The developer uses this tab to create specific table bindings that are not in the data set. Click on ADD,
then create the desired binding.

In this case, the binding jpke y was added to the table binding.

The New Data Binding Column allows the practitioner to enter a Name, Data Type, and Expression.

53
The ellipsis button launches the Expression builder.

Here, the developer enters the desired expression. This value entered will be discussed in the next section on
Grouped Reports.

Grouped
Using the same report to demonstrate grouping, when the practitioner reviews the Groups section of the
outline, the details are displayed in the Group’s diaglog box.

By double clicking on the TableGroup component, the

practitioner sees the following dialog box:

54
In the Group On drop down box, available elements from the table binding allow the developer to select how
the data will be grouped. Page Breaks for Befor e and After are determined in this dialog box, as well.

The use of internals allows the grouping to use additional characteristics of the value chosen. For example, if
the group on key was a date attribute, then the interval could be by Day, Week, Month, Q uarter, etc.

The TOC Item Expression for the Table of Contents feature in the Web Viewer and the Filtering and sorting
within the group may also be set by the developer in this dialog box.

4
Summary of Custom Report Functions
IBM created the following fu nctions (methods) in order to integrate BIRT fully into the TPAE framework. By
carefully reading this section, and referring to it as needed, the practitioner will successfully deploy these
methods in customer reports and report modification to existing bu siness logic. A short synopsis for each
method helps the practitioner understand the usage and context of each method.

Maximo Report Methods

55
MXReportSqlFormat.class Methods
The following methods aid the practitioner in manipulating the SQL that is passed t o the database when the
report is executed.

createParamWhereClause(String columnName, String paramValue)

The developer uses this method to create an additional criterion, to concatenate into the SQL for a report.
This function is similar to the parseParam2 function from the Maximo 6/Actuate 8 era.

Usage: createParamWhereClause(WORKORDER.STATUS, myStatus) Note:

param myStatus = “= ‘APPR’”
Result: “ workorder.status = ‘APPR’ ”

Usage: createParamWhereClause(WORKORDER.STATUS, myStatus) Note:

param myStatus = “= ‘APPR’; = ‘WAPPR’”
Result: “ (workorder.status = ‘APPR’ OR workorder.status = ‘WAPPR’) ”

The myStatus parameter is populated by the user through a request page parameter set up in Maximo.

getCombinedDateAndTime(Date date, Date time)

This function returns a combined Date and time in Long format

Usage: getCombinedDateAndTime(‘9/19/2009’, ‘16:00’)

Result: Saturday September 19, 2009 4:00 PM

getCurrentDateFunction()
This function returns the current system date from the server

Usage: getCurrentDateFunction()
Result: Friday July 24, 2009

getCurrentTimestampFunction()
This function returns the current system time from the server

Usage: getCurrentTimestampFunction()
Result: 4:12 PM

56
getDouble(string)
This is used in the fetch method to populate the row variable with the data from the data set open method.

Usage: row["conversion"] = LSTconversionDataSet.getDouble("conversion")

Result: The Row value is set to the value of the data set’s “conversion”

getEndDayTimestamp(Date d)
This function takes the value from the output to the above function and when used in the SQL Text portion of
a data set method formats the value to be used in the SQL call to the database

Usage: var lastDate =

MXReportSqlFormat.getEndDayTimestamp(DateTimeSpan.addDate(currDate, -1,0,0)); Result: Date value
at beginning of day (e.g. 1/1/2009 23:59:59)

getEndDayTimestampFunction(Date d)

Usage: + " where transdate between " +

MXReportSqlFormat.getTimestampFunction(firstDate)
+ " and " + MXReportSqlFormat.getTimestampFunction(lastDate)
Result: When the SQL is passed to the database the SQL looks like this:
where transdate between { ts '2009-10-08 00:00:00' } and
{ ts '2008-10-08 23:59:50' }

getStartDayTimestamp(Date d)
This function is used in a method where the developer wants to format a variable into a meaningful format to
be used later in the SQLof a data set call.

Usage: var currDate = new Date();

var firstDate = MXReportSqlFormat.getStartDayTimestamp(currDate);
Result: Date value at beginning of day (e.g. 1/1/2009 00:00:00)

getTimestampFunction(Date d)
This function takes the value from the output to the above function and when used in the SQL Text portion of
a data set method formats the value to be used in the SQL call to the database

Usage: + " where transdate between " +

MXReportSqlFormat.getTimestampFunction(firstDate)
+ " and " + MXReportSqlFormat.getTimestampFunction(lastDate)
Result: When the SQL is passed to the database the SQL looks like this:
where transdate between { ts '2009-10-08 00:00:00' } and
{ ts '2008-10-08 23:59:50' }

MXReportDataSetProvider.create(String dataSourceName, String

dataSetName)
This method is typically used in the beginning of each Open method for every report. It is also used to
create an artifact during a fetch method that can aggregate row level data.

Usage: MXReportDataSetProvider.create(this.getDataSource( ).getName(),

"childlabcostDataSet") ;
Result: A data set called childlabcostDataSet is created. See example below in chater five for
further details.

57
MXReportTxnProvider.create(“maximoDataSource”);
This method is used to create a data set that will receive an update statement. This is a typical way of
doing this.
Usage: myTxn = MXReportTxnProvider.create("maximoDataSource");
Result: A NEW data source artifact is created in memory. It is available for later processing.

NOTE: the usage in the example above is in section five.

5
Sample Usage of Methods
This section gives the practitioner a few samples (taken from existing reports) on how to implement the
methods outlined in the previous se ction.

Example Report Methods

beforeOpen Method
This code is used for an update report. The update reports work in tandem with the initial report that displays
the data using a variety of calculations (e.g. Asset Cost Rollup, Inventory Reorder Point, Inven tory Economic
Order Quantity, etc.)

if(params["paramstring"] == "update"){
request = reportContext.getHttpServletRequest();
if(request != null){
session = request.getSession();
updated = session.getAttribute("costrollup_update_status");
}
}

The initial report will have calculations (usually) in the Fetch method and will then create update statements
that are stored in the session. The actual update report is then called from a push button located on the initial
report, which then calls the stored session i nformation and processes it.

Open Method
Conditional logic used in the open method determines which database syntax to use. Below is a useful syntax
for conditional logic example:

maximoDataSet = MXReportDataSetProvider.create(this.getDataSource().getName( ),
this.getName());
maximoDataSet.open();

var sqlText = new String();

if(params["paramstring"] == "update") params["where"] = " 1=2 ";

if(maximoDataSet.isSQLServer()){
assetDescription = " asset.assetnum + char(10) + asset.description ast, ";
}else assetDescription = " asset.assetnum || chr(10) || asset.description ast, ";

Create the various needed data sources for the update statements.

58
 myTxn = MXReportTxnProvider.create("maximoDataSource");
matTxn = MXReportTxnProvider.create("maximoDataSource");
labTxn = MXReportTxnProvider.create("maximoDataSource");
servTxn = MXReportTxnProvider.create("maximoDataSource");
toolTxn = MXReportTxnProvider.create("maximoDataSource");

sqlText = "select " + assetDescription + " coalesce(asset.totalcost,0) as totalcost, "

+ "coalesce(asset.ytdcost,0) as ytdcost, "
+ "coalesce(asset.budgetcost,0) as budgetcost , asset.description, asset.assetnum,
asset.siteid, assetuid "
+ "from asset "
+ "where ( "
+ "exists "
+ "(select 1 from labtrans where labtrans.assetnum=asset.assetn um and
labtrans.genapprservreceipt = 1 "
+ "and labtrans.siteid=asset.siteid and labtrans.rollup = 0) "
+ "or exists "
~~~~~~~~~~~~~~~~SNIP~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ " order by asset.assetnum";

maximoDataSet.setQuery(sqlText);

Fetch Method
Typically, the Fetch method is used to process business logic on a row -by-row basis. In the Asset Cost Roll -up
report, various components of each asset’s cost is calculated, totaled, and displayed.

if (!maximoDataSet.fetch())
return (false);

validatedRecord = false;

while (!(validatedRecord)) {
labcost = 0;
matcost
= 0;
servcos
t = 0;
toolcos
t = 0;

// Lab Cost
labcostDataSet = MXReportDataSetProvider.create(this.getDataSource().getName(),
"labcostDataSet");
labcostDataSet.open();

labcostSQL = "select sum(labtra ns.linecost) as linecost from labtrans, workorder "

.....set your SQL statement here.....

Accumulation of labor cost.

if(labcostDataSet.fetch()) {
labcost = labcost + labcostDataSet.getDouble("linecost");
}
// End Lab Cost

// Child Lab Cost

childlabcostDataSet =
MXReportDataSetProvider.create(this.getDataSource().getName(), "childlabcostDataSet");
childlabcostDataSet.open();

childlabcostSQL = "select sum(labtrans.linecost) as linecost from

labtrans, assethierarchy, workorder "
+ "where labtrans.siteid=wo rkorder.siteid and labtrans.refwo=workorder.wonum "
.....set your SQL statement here.....

if(childlabcostDataSet.fetch()) {
labcost = labcost + childlabcostDataSet.getDoubl e("linecost");
}
// End Child Lab Cost

59
Total Cost calculated.

temptotalcost = labcost + matcost + servcost + toolcost;

if (temptotalcost > 0) {
row["ast"] = maximoDataSet.getString("ast");
row["totalcost"] = maximoDataSet.getDouble("totalcost");
.....
validatedRecord = true;

myStmt = myTxn.createStatement();
myStmt.setQuery("update asset set totalcost = " + row["newtotalcost"] + ", ytdcost =
" + row["newytdcost"] + " "
+ " where assetuid=" + maximoDataSet.getInteger("assetuid"));

// myTxn is saved in session and all updates are executed in

beforeOpen method when the report is self-called through the
hyperlink
request = reportContext.getHttpServletRequest();
session = request.getSession();
session.setAttribute("TxnUpdate", myTxn);

Using the various data sources created in the open Method, set the update SQL here:

matUpdtStmt = matTxn.createStatement();
sqlStmt = "update matusetrans set matusetrans.linecost = 0 where "
.....set your SQL statement here.....

Then set the query with this statement:

matUpdtStmt.setQuery(sqlStmt);

Then set session attribute in order to enabl e execution of the SQL:

session.setAttribute("TxnMatUpdate", matTxn);

labUpdtStmt = labTxn.createStatement();
sqlStmt = "update labtrans set labtrans.linecost = 0 where "
.....set your SQL statement here.....

labUpdtStmt.setQuery(sqlStmt);
session.setAttribute("TxnLabUpdate", labTxn);

servUpdtStmt = servTxn.createStatement();
sqlStmt = "update servrectrans set servrectrans.linecost = 0 where "
.....set your SQL statement here.....

servUpdtStmt.setQuery(sqlStmt);
session.setAttribute("TxnServUpdate", ser vTxn);

toolUpdtStmt = toolTxn.createStatement();
sqlStmt = "update tooltrans set tooltrans.linecost = 0 where "
.....set your SQL statement here.....

toolUpdtStmt.setQuery(sqlStmt);
session.setAttribute("TxnToolUpdate", toolTxn);
}
else {
if (!maximoDataSet.fetch())
return (false);
}

} //end while

60
 // Compare YTD Current with YTD Dynamic (if same do nothing, otherwise display record)

return (true);

beforeClose Method
This method properly closes all of the temporary data sets opened in the processing of the report.

if(params["paramstring"] != "update"){
request = reportContext.getHttpServletRequest();
if(request != null){
session = request.getSession();

myTxn = session.getAttribute("TxnUpdate");
matTxn = session.getAttribute("TxnMatUpdate");
labTxn = session.getAttribute("TxnLabUpdate");
servTxn = session.getAttribute("TxnServUpdate");
toolTxn = session.getAttribute("TxnToolUpdate");

if(myTxn != null && matTxn != null && labTxn != null && servTxn != null && toolTxn != null){
myTxn.save();
matTxn.save();
labTxn.save();
servTxn.save();
toolTxn.save();
updated = true;
session.setAttribute("costrollup_update_status", true);
myTxn = null;
matTxn = null;
labTxn = null;
toolTxn = null;
servTxn = null;
session.setAttribute("TxnUpdate", null);
session.setAttribute("TxnMatUpdate", null);
session.setAttribute("TxnLabUpdate", null);
session.setAttribute("TxnServUpdate", null);
session.setAttribute("TxnToolUpdate", null);
}else{

session.setAttribute("costrollup_update_status", false);

}
}
}

61
Other Methods
Initialize Method
The templates override the initialize method to introduce the script context classes.

The default method looks like this:

importPackage(Packages.com.ibm.tivoli.maximo.repor t.script);

mxReportScriptContex t = MXReportScriptContext.init ialize(reportContext);

Using the Job Plan Report (jobplan.rptdesign) the practitioner sees that a good example of code is as follows:

importPackage(Packages.com.ibm.tivoli.maximo.repor t.script);

mxReportScriptContex t = MXReportScriptContext.init ialize(reportContext) ;

mxReportScriptContext.setDefaultLogLevel( "DEBUG");
mxReportScriptContext.setDefaultLogFile( "c:/temp/myreport.log" );

function hyperlinkWhere(jpnum , orgid, siteid)

{
var hlink = new String();

hlink = "jobplan.jpnum='" + jpnum + "'";

if(BirtComp.notEqual(o rgid, "") && BirtComp.notEqual(orgid , null))

hlink += " and jobplan.orgid='" + orgid + "'";
if(BirtComp.notEqual(siteid , "") && BirtComp.notEqual(siteid , null))
hlink += " and jobplan.siteid='" + siteid + "'";

return hlink;
}

Notice that a function is cr eated here and is referenced through out the report. A key thing to note here is how
the debugging is set up. The blue text indicates the debug level, as well as the target for the report.

Here is another example of custom override on the initialize method:

importPackage(Packages.com.ibm.tivoli.maximo.repor t.script);

mxReportScriptContex t = MXReportScriptContext.init ialize(reportContext) ;

var maintable = "";

mxReportScriptContext.setDefaultLogLevel( "DEBUG");
mxReportScriptContext.setDefaultLogFile( "C:/temp/cah_ar2_case_resolution_type.l o
g");

scriptLogger = mxReportScriptContext.getReportScri ptLogger();

In this example, a global variable is created. This allows the practitioner to set and access a variable that has
global scope but is NOT a parameter. This is important in that a report parameter will be imported into the
Maximo framework during the “Report Import” process, whereas the global variable will not.

63
afterFactory
The afterFactory method has this standard code in the template:

MXReportScriptContext .close();

This enables the closing of the dataset during report runtime.

User Functions (in any method)

Use of a second data set during the open method enables the developer to process additional data outside of
the initial SQL used for the report’s main d ata. This is helpful when the developer wants to add the name of the
person executing the report to the report’s display.

The process automation engine passes the logged -in user’s credentials to the report engine at runtime as a
part of a number of different parameters. The user’s ID (username) can then be used in the following method
to get the PERSON record’s DISPLAYNAME attribute.

// User's Display Name

userDispNameDataSet = MXReportDataSetProvider.create(this.getDataSource().getName(),
"userDispNameDataSet");
userDispNameDataSet.open();

userDispNameSQL = "select DISPLAYNAME from person where personid = "

+ "(select personid from maxuser where userid = upper('" + params[" userName"] + "'))"

userDispNameDataSet.setQuery(userDispNameSQL);

if(userDispNameDataSet.fetch()) {
params["displayname"] = userDispNameDataSet.getString("displayname");
}
userDispNameDataSet.close();

// End User's Display Name

The parameter “username” must be added to the report along with the parameter “displayname” (as indicated
below) in order for this to work.

NOTE: The parameter “username” is case sensitive.

64
6
Reporting Best Practices
This section describes what practitioners should consider as standards and techniques that define the most
appropriate manner in which custom r eports should be developed to best integrate th em with the standard
OOTB reports from IBM.

Look and Feel

MaximoSystemLibrary.rptlibrary
The delivered library contains the style sheet for the common presentation across ALL reports. Since this
library is stored in the database when the product is delivered, if the client want to affect changes in the look
and feel of the reports, the practitioner is advised to make these kinds of changes once in the Library so that,
when the OOTB reports use the library, the reports all behave the same.

Practice and care is required in order to ensure that custom and modified reports properly reference the
objects stored and/pr modified in the updated library. When changes are made in the library file, any logos
used in the updated library must be re-imported. Otherwise, the images do not render correctly.

Standardized Functionality
Common Methods and Techniques
The code that is delivered with several reports enables consistency across similar applications. For example,
the WORINT.RPTDESIGN file is used in “clone” applications (i.e. QUICK, WOACTIVITY, and WOCHANGE
are all clones of WOTRACK). As such, the common report amongst those applications is a single report that
uses the appName parameter that is established in the Maximo Templates.

Similarly, the SR, INCIDENT, and PROBLEM applications’ reports all rely on the und erlying TICKET object
rather than each applications’ view. The standardized code in these reports enables any report developed for
the TICKET object to be used in any application whose main object is based on the TICKET object.

With the above statements made, the practitioner is strongly advised to create reports for the above
applications using the standards as set forth in the code in these reports.

For example: The TICKET.RPTDESIGN report uses a global variable defined in the initialize method to allow
the report to look to the application ’s “MAINTABLE” value in the MAXAPPS object. A function in the main data
set “open” method then obtains this information and re places the Application’s value with “ticket;” thereby,
modifying the SQL where clause to work against the TICKET object instead of SP, PROBLEM, or INCIDENT.

Understanding TPAE Integration

Review of Common Method Overrides or “Plagiarism for Productivity”
IBM provides its clients with the source code for all out -of-the-box (OOTB) reports. This enables our clients to
use this code to do two things.

1. Modify the existing reports to meet specific client requirements

2. Allow the clients to use the existing code as t emplates for further report development

As such, the well-informed practitioner will use the existing reports as a model for further report development.
Examining existing reports for code examples is not only suggested, but also strongly recommended.

65
The following reports have code s that are great samples for practitioners to use:

 jobplan.rptdesign

o hyperlink function

 ticket.rptdesign

o ability to use with multiple applications

 ticketprint.rptdesign

 woprint.rptdesign

o ability to use with multiple applications

 wotrack.rptdesign

o hyperlink function

 inventory_rop.rptdesign

o samples of code calculations

 inventory_eog_tbl.rptdesign

o samples of code calculations

 asset_costrollup.rptdesign

o samples of code calculations

The designers of these reports took different approa ches in some of these techniques such that some of the
samples do the same thing but with a different style. These samples will enable the practitioner to develop his
or her own style but still have the reports work effectively within the TPA E

66
1