BIRT for Tivoli Process Automation EngineImplementation Guidelines

By Bradley K. Downing, MBAVersion 1.5

iii

Copyright Notice

Copyright IBM Corporation 2010. All rights reserved. May only be used pursuantto a Tivoli Systems Software License Agreement, an IBM Software LicenseAgreement, or Addendum for Tivoli Products to IBM Customer or LicenseAgreement. No part of this publication may be reproduced, transmitted,transcribed, stored in a retrieval system, or translated into any computerlanguage, in any form or by any means, electronic, mechanical, magnetic,optical, chemical, manual, or otherwise, without prior written permission ofIBM Corporation. IBM Corporation grants you limited permission to make hardcopyor other reproductions of any machine-readable documentation for your own use,provided that each such reproduction shall carry the IBM Corporation copyrightnotice. No other rights under copyright are granted without prior writtenpermission of IBM Corporation. The document is not inte nded for production andis furnished “as is” without warranty of any kind. All warranties on thisdocument are hereby disclaimed, including the warranties of merchantability andfitness for a particular purpose.

U.S. Government Users Restricted Rights -- Use, duplication or disclosurerestricted 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 seConsole, Tivoli Ready, and TME are trademarks or registered trademarks ofInternational Business Machines Corporation or Tivoli Systems Inc. in theUnited States, other countries, or both.

Lotus is a registered trademark of Lotus Development Corporation .Microsoft, Windows, Windows NT, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.UNIX is a registered trademark of The Open Group in the United States and othercountries.C-bus is a trademark of 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 IntelCorporation in the United States, other countries, or both. For a complete listof Intel trademarks, see http://www.intel.com/sites/corporate/trademarx.htm.SET and the SET Logo are trademarks owned by SET Secure Electronic TransactionLLC. For further information, see http://www.setco.org/aboutmark.html.Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries.

Other company, product, and service names may be trademarks or service marks ofothers.

Notices

References in this publication to Tivoli Systems or IBM products, programs, orservices do not imply that they will be available in all countries in whichTivoli Systems or IBM operates. Any reference to these products, programs, orservices is not intended to imply that only Tivoli Systems or IBM products,programs, or services can be used. Subject to valid intellectual property orother legally protectable right of Tivoli Systems or IBM, any functionallyequivalent product, program, or service can be used instead of the referencedproduct, program, or service. The evaluation and verification of operation inconjunction with other products, except those expressly designated by Tivo liSystems or IBM, are the responsibility of the user. Tivoli Systems or IBM mayhave patents or pending patent applications covering subject matter in thisdocument. The furnishing of this document does not give you any license tothese patents. You can send license inquiries, in writing, to the IBM Directorof Licensing, IBM Corporation, North Castle Drive, Armonk, New York 10504 -1785,

iv

U.S.A.

v

Acknowledgements

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

vii

About the Tivoli Field Guides

SponsorTivoli Customer Support sponsors the Tivoli Field Guide program.

AuthorsThose 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

AudienceThe field guides are written for all customers, both new and existing. They are ap plicable toexternal audiences including executives, project leads, technical leads, team members, and tointernal audiences as well.

Types of Field GuidesTwo types of Tivoli Field Guides describe how Tivoli products work and how they are used in reallife situations:

Field Guides for technical issues are designed to address specific technical scenarios orconcepts 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 thathave a high impact on the success or failure of an ESM project, for example: changemanagement, asset Management, and deployment phases.

PurposesThe Field Guide program has two major purposes:

To empower customers & business partners to succeed with Tivoli software bydocumenting and sharing product information that provides accurate and timelyinformation on Tivoli products and the business issues that impact an enterprise sy stemsmanagement project

To leverage the internal knowledge within Tivoli Customer Support and Services and theexternal knowledge of Tivoli customers and Business Partners

AvailabilityAll completed field guides are available free to registered customers and internal IBM employeesat 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:

viii

mailto:Tivoli_eSupport_Feedback@us.ibm.com

ix

Table of Contents

IMPLEMENTATION GUIDELINES............................................................. I

Sponsor................................ ................................ ................................ ...viiAuthors ................................ ................................ ................................ ...viiAudience ................................ ................................ ................................ .viiTypes of Field Guides ................................ ................................ ............ viiPurposes................................ ................................ ................................ .viiAvailability ................................ ................................ .............................. vii

IMPLEMENTATION GUIDELINES.......................................................... 13

INSTALLING BIRT INTO IBM’S TIVOLI PROCESS AUTOMATIONENGINE V7 FRAMEWORK....................................................................... 13

BIRT TOOL SETUP REQUIREMENTS ................................ ................................ ............... 13

IBM Employees................................ ................................ ............................ 13Non-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 ................................ ................................ ................................ ..30The open method ................................ ................................ ................... 32The Fetch Method ................................ ................................ .................. 33The Initialize Method ................................ ................................ ..............33

WOPRINT................................ ................................ ................................ ....34INVENTORY_ROP and INVENTORY_ROP_UPDATE ............................... 35

The ROP Initialize Method ................................ ................................ .....35The UPDATE Initialize Method ................................ .............................. 35The ROP Open Method ................................ ................................ ..........37

x

The ROP Fetch Method ................................ ................................ ..........39LOCALIZATION SETUP................................ ................................ ................................ .... 41

How Localization is Enabled ................................ ................................ ........42How Report Labels get Localized ................................ ................................ 43Request Pages ................................ ................................ ............................ 45

Static Content ................................ ................................ ......................... 46Dynamic Content ................................ ................................ .................... 46

Common Customer Scenarios ................................ ................................ .....47

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

REPORT TYPES ................................ ................................ ................................ ............... 48

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

SUMMARY OF CUSTOM REPORT FUNCTIONS .................................. 55

MAXIMO REPORT METHODS ................................ ................................ .......................... 55

MXReportSqlFormat.class Methods ................................ ............................ 56createParamWhereClause(String columnName, String paramValue) 56getCombinedDateAndTime(Date date, Date time) ............................... 56getCurrentDateFunction() ................................ ................................ ......56getCurrentTimestampFunction() ................................ ........................... 56getDouble(string)................................ ................................ .................... 57getEndDayTimestamp(Date d) ................................ ............................... 57getEndDayTimestampFunction(Date d) ................................ ................57getStartDayTimestamp(Date d) ................................ .............................. 57getTimestampFunction(Date d) ................................ ............................. 57

MXReportDataSetProvider.create(String dataSourceName, StringdataSetName) ................................ ................................ .............................. 57MXReportTxnProvider.create(“maximoDataSource”); ................................ ..58

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

EXAMPLE REPORT METHODS ................................ ................................ ......................... 58

beforeOpen Method ................................ ................................ ..................... 58Open Method ................................ ................................ ............................... 58

xi

Fetch Method ................................ ................................ ............................... 59beforeClose Method ................................ ................................ .................... 61

OTHER METHODS................................ ................................ ................................ ........... 63

Initialize Method ................................ ................................ ........................... 63afterFactory................................ ................................ ................................ ..64User Functions (in any method) ................................ ................................ ...64

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

LOOK AND FEEL................................ ................................ ................................ ............. 65

MaximoSystemLibrary.rptlibrary ................................ ................................ ..65STANDARDIZED FUNCTIONALITY ................................ ................................ ................... 65

Common Methods and Techniques ................................ ............................. 65UNDERSTANDING TPAE INTEGRATION................................ ................................ .......... 65

Review of Common Method Overrides or “Plagiarism for Productivity” .......65

13

BIRT for Tivoli Process Automation Engine (Maximo)7.xImplementation Guidelines

The purpose of this guide is to enable the Maximo develope r to install and modify existing report source codeusing 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 implementationand 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 forEnterprise IT and Asset Management 7.1) before using this guide in depth.

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

BIRT Tool Setup RequirementsIBM EmployeesDownload 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 followingcomponents 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:

14

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 completeinstructions: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 download thesecomponents from the IES Website.

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

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 andsave the file to your directory.

15

d. On the same page, locate the Business Intelligence and Reporting Tools SDK and save thefile 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

16

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 looklike 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/50servicerelease4windowsia32pwi32dev20070201j9/index.html

Non-IBM Employeesa. 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.

17

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

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

18

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 berequired to check a License agreement checkbox.

19

f. Now Click on “I confirm”

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

20

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

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

Installing V7 Design Files for BIRTA local copy of Maximo V7, with the report source, is required in order to perform the next steps. Additionally, inthe file paths below, v20070205-1728 is a version number and may be slightly different depending on theEclipse 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.

21

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 localenvironment 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 tocopy 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 connectioninformation 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&nowarnings=true

# driver for DB2

# com.ibm.db2.jcc.DB2Driver

# 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

22

maximoDataSource.password=maximo

The values in red point to a sample local database. You can check yours and other s that are available for youto 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 towork 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 filesinto the “classes” folder, which was created in step 2.b (above).

Accessing the BIRT Designer1. 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}:\programfiles\IBM\Java50\bin\javaw.exe" -vmargs -Xmx512m

23

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

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

24

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

25

5. Type in a project name and click Finish.

26

6. The BIRT Report designer within Eclipse SDK Displays.

27

Configuring BIRT Report Designer to Work with V7Configuration FilesNOTE: 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 open (below), then select from the menu, “Window |Preferences.”

b. Expand Report Design and select Templates

28

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.

29

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.

30

6. Click Finish.

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

Maximo Standard Reports InterfaceWOTRACKThis screen shot is of the WOTRACK report, in the Eclipse Developer Interface using the BIRT plugin.

31

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 requiresattention:

1. Click on the desired data set in either the Data Explorer tab or the Outline View tab. By default, both arelocated on the left-hand side of the screen.

32

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 initialselection.

33

The Fetch Method

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

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

The Initialize MethodUnlike the first two methods located on the Data Set, the initialize method is located on the main report designcomponent. 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.

34

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

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

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

WOPRINTThe next report that has interesting meth ods to study is the Work Order Details Report. 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 inthe main data set “open” method. Since this dataset open method is embedded on the Fetch method of themain data set, it will retrieve the long description for each record in the data set.

35

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

INVENTORY_ROP and INVENTORY_ROP_UPDATEThe inventory ROP report provides the users of the Maximo Asset Management suite a standardized methodfor keeping the Reorder Point of the Maintenance and Repair Operation (MRO) Inventory up -to-date based onusage.

The ROP Initialize MethodThis method sets two variables to enable the update report to work. These variables are used to track theupdate time.

importPackage(Packages.com.ibm.tivoli.maximo.report.script);

mxReportScriptContext = MXReportScriptContext.initialize(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 MethodThe report starts with an override of the Initialize method , which determines whether the update statement willbe 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);

}

36

updStmtList.length);

if(updStmtList!=null){var updTxn = MXReportTxnProvider.create(dsName);for(var i=0; i < updStmtList.length; i++) {

var updStmt = updTxn.createStatement();updStmt.setQuery(updStmtList[i]);if (scriptLogger.isDebugEnabled()) {

scriptLogger.debug(" >>> updStmt #" + (i+1) + " of " +}

37

}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.removeHttpSessionAttribute(params["paramstring"]);

}}

}

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

The ROP Open MethodIn this method, the session context allows the interaction of the update report to ca ll the ROP calculation withthe appKey and dsKey parameters. Subsequently , the “where” clause is built dynamically based on the user’sinput. The Lead Time in months is set based on the Start Date entered by the user. Due to differences indatabase syntax restrictions, the total items clause is structured accordingly. Finally, the SQL is properlyconstructed 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[ "location"],''))) {

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"]);}

lTimeMonthsClause = " floor("+ DateTimeSpan.months(params["startdate"], new Date()) + ") as

leadtimemonths, ";

38

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, ";

elsetotalItemsClause = " ((select count(*) from matrectrans where

39

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

totalitems, "

sqlText = "select distinct inventory.itemnum as itemnum, item.description asdescription, "+" inventory.orderunit as orderunit, inventory.minlevel as minlevel,inventory.deliverytime as delivery,"+" inventory.sstock as sstock, " + lTimeMonthsClause + " inventory.itemsetid asitemsetid,"+ totalItemsClause+" conversion.conversion as conversion, inventory.location as location,inventory.siteid as siteid "+" from item, inventory "+" left outer join matusetrans on inventory.itemnum = matusetrans.itemnum "+" and inventory.itemsetid = matusetrans.itemsetid "+" and inventory.siteid = matusetrans.siteid "+" and inventory.location = matusetrans.storeloc "+" left outer join "+" matrectrans on inventory.itemnum = matrectrans.itemnum "+" and inventory.itemsetid = matrectrans.itemsetid "+" and inventory.siteid = matrectrans.siteid "+" and inventory.location = matrectrans.tostoreloc "+" left outer join conversion on inventory.itemnum=conversion.itemnum "+" 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.location "+" order by inventory.itemnum, item.description,inventory.orderunit,inventory.minlevel , inventory.sstock,inventory.deliverytime, inventory.itemsetid, conversion.conversion,inventory.siteid, inventory.location ";

maximoDataSet.setQuery(sqlText) ;

The ROP Fetch MethodThe report starts with an override of the Initialize method , which determines whether the update statement willbe executed during the processing of the report. Next, a number of variables are created to allow theprocessing of the ROP set point. Allowing for a normalization of the number of days in any given month, thealgorithm uses conversion factors (if used) to set the safety stock, which is finally used to set the Re -OrderPoint. Once the point has been calculated , if the update report, calls this report the update statements are usedto 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");

40

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

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

if((maximoDataSet.getInteger("totalitems")==0)||(maximoDataSet.getInteger("leadtimemonths")==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( "totalitems")*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;

41

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 SetupTwo 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 reportadmin app for each of these different language s. This can best be described by the use case below.

42

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, andgenerate the request pages xml in English.

c. Next, he would sign out. He would then sign back in and change his locale to Spanish. Hewould 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, andgenerate the report request pages in Italian.

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

How Localization is EnabledOnce 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 ofBASELANGUAGE.

If the user’s language is the same as the MAXVAR’s base language setting, then V7 and reportingwill 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 Reportingwill retrieve data from the corresponding localized tables (e.g. Report labels come fromL_REPORTLABEL where Language Code is equal to the Language Code of the End User).

This is shown below:

43

How Report Labels get LocalizedAll report labels and titles are referenced in their design file by key values. The key value s are simply uniquetext 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 andSuccess.

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

For clients using a language other then English, or for clients enabl ing multiple languages in a V7environment, corresponding database tables identified by L_REPORTLABEL will be used. These tables willhold 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. Thecombination of the Label Value and Language Code will make the label value unique.

L_REPORTLABEL.REPORTLABELID L_REPORTLABEL.LANGCODE L_REPORTLABEL.LABELVALUE12345 ES mi primer informe12345 FR mon premier rapport12346 ES fecha12346 FR date

Labelkey and Labelvalues for each control in each report have to be defined by the Report Developer. Thisoccurs 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, thedeveloper needs to enable the labels for localization. To do this, the practitioner performs the following steps:

1. Click on the Layout Tab, Property Editor.

44

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.

45

As the values are added, the properties file is updated. A sample o f the wotrack.properties file is shownbelow. The first value on the left is the label key, and the second value on the right is the label value. Thelabel 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, forexample, 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 havereports.

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

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

46

Static ContentWhen 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 theL_MAXMESSAGE table and the dialog loader would populate the L_MAXLABEL with the same localizedcontent as in L_MAXMESSAGE table.

This means that the dialogs need to be generated from every language that we support in order to populatethe 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 isinvoked.

Dynamic ContentWhen the dialog is generated using the Generate XML process, the REPO RTLOOKUP table contents areused. 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 theL_REPORTSLOOKUP table and the dialog loader would populate the L_MAXLABEL with the same localizedcontent as in the L_REPORTLOOKUP table. This means that the dialogs need to be generated for everylanguage that we support in order to populate the L_MAXLABEL table. When the dialog is shown, theL_MAXLABEL values are used.

47

NOTE: the MAXLABEL and L_MAXLABEL values are overwritten every time the Generate XML operation isinvoked.

Common Customer ScenariosIn 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 eachclient setup.

Customer 1 Customer 2 Customer 3

Base Language English French FrenchSecondary Language Spanish

MAXINST Database Created English English EnglishLoads Localiz-able Report Tables REPORT, REPORTLABELS, REPORTLOOKUP REPORT, REPORTLABELS, REPORTLOOKUP REPORT, REPORTLABELS, REPORTLOOKUP

Creates Property FilesBecause English DB, calls method, butnothing happens

Because English DB, calls method, butnothing happens

Because English DB, calls method, butnothing happens

TDTExtracts XLIFF (3 Files for: REPORT,REPORTLABEL, REPORTLOOKUP)Base Language Conversion? No Yes. Converts Base to French Yes. Converts Base to FrenchLoads all report data based on report.xml* Loads French Data Loads French DataCreates L_Tables No No Yes. L_ for Spanish Values

Create Properties Create report properties NoYes. Retain Original, create new forFrench

Yes. Retain Original, create new forFrench, Spanish

jobplan.properties jobplan.properties jobplan.propertiesjobplan_FR.properties jobplan_FR.properties

jobplan_SP.properties

Start MX ServerLoads all Report Tables based onreport.xml

*During startup, MX sees FR database,so does not overwriteREPORT.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 formatting. However, due to localization issues, clients are encouraged to use onlyShort, Medium, or Long Date/Time formatting for their custom reports.

B. Hyperlinks

48

If a user hyperlinks from one BIRT report to another, no additional code is required for localizatio n. Thelanguage 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 thatknows about the already logged in user and the user’s locale/languagecode/timezone information. Thisinformation is automatically passed to the BIRT engine or to our scripting code through a framework providedreport context.

C. Fonts

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

If a client wants to change the font of the BIRT reports to a Unicode or other format, he would change theStyle Sheet used in the Report 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 notavailable, it will use Helvetica.

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

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

49

This list of work orders displays several columns of data for each work order. To add columns to this, youmust 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 thosecolumns.

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

50

1. Modify the SQL in the Open Method to add the new attribute.

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

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 correctmethod 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.

51

Focus on the Data set either in the Data Sets tab or in the Outline view. D ouble click on the dataset or chooseEdit 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 asdefined 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 thenew 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 nextto last), please try to use only “Column to the Left.” When the practitioner chooses “Column to the Right,” itmay 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 -createdattribute from the data set onto the desired location in the report.

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

52

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. Thisis called Table Binding.

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

53

table. The tables are executed in descending order, from top to bottom. This is more readily displayed in thelayout 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 jpkey was added to the table binding.

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

54

The ellipsis button launches the Expression builder.

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

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

By double clicking on the TableGroup component, the

practitioner sees the following dialog box:

55

In the Group On drop down box, available elements from the table binding allow the developer to select howthe 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, ifthe 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 sortingwithin the group may also be set by the developer in this dialog box.

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

Maximo Report Methods

56

MXReportSqlFormat.class MethodsThe following methods aid the practitioner in manipulating the SQL that is passed t o the database when thereport 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

57

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 ofa 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 valueat 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 tobe 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 ofa 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, StringdataSetName)This method is typically used in the beginning of each Open method for every report. It is also used tocreate 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 forfurther details.

58

MXReportTxnProvider.create(“maximoDataSource”);This method is used to create a data set that will receive an update statement. This is a typical way ofdoing 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.

5Sample Usage of MethodsThis section gives the practitioner a few samples (taken from existing reports) on how to implement themethods outlined in the previous section.

Example Report MethodsbeforeOpen MethodThis code is used for an update report. The update reports work in tandem with the initial report that displaysthe data using a variety of calculations (e.g. Asset Cost Rollup, Inventory Reorder Point, Inven tory EconomicOrder 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 statementsthat are stored in the session. The actual update report is then called from a push button located on the initialreport, which then calls the stored session i nformation and processes it.

Open MethodConditional logic used in the open method determines which database syntax to use. Below is a useful syntaxfor 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.

59

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 MethodTypically, the Fetch method is used to process business logic on a row -by-row basis. In the Asset Cost Roll -upreport, 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;servcost = 0;toolcost = 0;

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

labcostSQL = "select sum(labtrans.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 CostchildlabcostDataSet =

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

childlabcostSQL = "select sum(labtrans.linecost) as linecost fromlabtrans, assethierarchy, workorder "

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

if(childlabcostDataSet.fetch()) {labcost = labcost + childlabcostDataSet.getDoubl e("linecost");

}// End Child Lab Cost

60

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 inbeforeOpen method when the report is self-called through thehyperlink

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", servTxn);

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

61

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

return (true);

beforeClose MethodThis 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);

}}}

63

Other MethodsInitialize MethodThe 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);

mxReportScriptContext = MXReportScriptContext.initialize(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);

mxReportScriptContext = MXReportScriptContext.initialize(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(orgid, "") && 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 created here and is referenced throughout the report. A key thing to note here is howthe 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);

mxReportScriptContext = MXReportScriptContext.initialize(reportContext);

var maintable = "";

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

scriptLogger = mxReportScriptContext.getReportScri ptLogger();

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

64

afterFactoryThe 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 ofthe initial SQL used for the report’s main d ata. This is helpful when the developer wants to add the name of theperson 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 apart of a number of different parameters. The user’s ID (username) can then be used in the following methodto 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 indicatedbelow) in order for this to work.

NOTE: The parameter “username” is case sensitive.

65

6Reporting Best PracticesThis section describes what practitioners should consider as standards and techniques that define the mostappropriate manner in which custom r eports should be developed to best integrate th em with the standardOOTB reports from IBM.

Look and FeelMaximoSystemLibrary.rptlibraryThe delivered library contains the style sheet for the common presentation across ALL reports. Since thislibrary is stored in the database when the product is delivered, if the client want to affect changes in the lookand 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 theobjects stored and/pr modified in the updated library. When changes are made in the library file, any logosused in the updated library must be re-imported. Otherwise, the images do not render correctly.

Standardized FunctionalityCommon Methods and TechniquesThe 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 WOCHANGEare all clones of WOTRACK). As such, the common report amongst those applications is a single report thatuses 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 objectrather than each applications’ view. The standardized code in these reports enables any report developed forthe 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 aboveapplications 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 allowthe report to look to the application ’s “MAINTABLE” value in the MAXAPPS object. A function in the main dataset “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 IntegrationReview 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 touse 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.

66

The following reports have codes 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 thesamples do the same thing but with a different style. These samples will enable the practitioner to develop hisor her own style but still have the reports work effectively within the TPA E

1