IBM Maximo Asset Management

Version 6 External Report Integration

Copyright International Business Machines 2011 1

External Report Integration (ERI)

IBM Maximo Clients have a broad range of reporting needs. These needs may be set by their industries, or by their corporate standards. Additionally, clients may have in-house resources familiar with particular reporting tools. To respond to the diverse needs of Maximo clients, report integration functionality is available. This reporting functionality integrates Maximo with external reporting systems. These external Reporting Systems could be any of the wide variety of reporting tools in the marketplace today. The Reporting Integration enables the Maximo User to pass his application query to the external reporting system without having to leave the Maximo environment. Any number of report parameters can be passed either using the application query or not - to the external report system. This functionality is referred to as the External Report Integration (ERI.) It is very flexible as it is Report System and Report Version independent. This document details the Maximo ERI. After an overview of its functionality, the document includes information on 1. 2. 3. 4. 5. Requirements Enabling the Integration Registering and Running ERI Reports in Maximo Additional Details on ERI Frequently Asked Questions

Overview
The External Report Integration (ERI) enables you to integrate your reporting tool of choice within the Maximo Framework. The diagram below depicts this architecture at a very top level. In the center of the diagram, the Maximo server is displayed, and directly underneath it is a separate report server. Both of these servers are connected to the Maximo database filling and pulling from the vast amounts of its data. The key component to this integration is that the report server is integrated within Maximo. The user accesses Maximo and then Maximo directly communicates with the External Report Server. This integration is enabled in two key ways. First, the external reports are registered in Maximos Report Administration application. This enables them to be visible and accessed within the various Maximo applications. Secondly, a direct launch to the report server is enabled from Maximo. This occurs by passing critical report information from Maximo to the report server url specified in a maximo property file.

The ERI is best suited for a Maximo user who wants to directly access all of their Maximo reports from within the Maximo application.

Requirements of ERI
External Report System Requirements The External Report Server must provide a web-based interface. Maximo Version 6 will send required report-related information via an HTML form post to the URL specified in the Version 6 System Properties. Therefore, there must be a web application running at that URL that can receive the information, process it accordingly, and communicate with the Report Server in order to execute a report.

Support/Licensing IBM does not provide any additional external Reporting System Licenses with Version 6. Clients are responsible for the purchase and maintenance of their own External Report System Licenses. Additionally, IBM will not support issues with External Reporting Systems, related to the setup or maintenance of the Report Server, report development or debug of the system.

How to Set Up the ERI

Enabling V6 to integrate with your selected Reporting System requires three key components, which are: (1) additionalmaximo.properties 2) customreport.jsp (3) Password Encryption 1. additionalmaximo.properties A. Access the additionalmaximo.properties file, which is located in <Maximo root> applications\maximo\properties. Near the bottom of this file, locate the property settings related to the ERI. These are: //----------------------------------------------------------------------------// Properties for MXES integration with custom reporting tool. // Customer-defined properties may be added by prefixing the property name with "mxe.report.custom". //----------------------------------------------------------------------------// URL of the custom reporting application //mxe.report.custom.serverURL=http://reportServer:7001/reportApp/customReport.jsp // Password used for logging on to report server administration tool; will be encrypted before sending to the reporting application. //mxe.report.custom.rptServerLogonPass=myPassword B. Copy and paste these two values from the additionalmaximo.properties to the end of the maximo.properties file located in: <Maximo root>\applications\maximo\properties

*For clients on Version 6.2.8 and higher see note below.

C. Uncomment the property settings by removing the // from the start of each line, and input the correct, required values. Note: If you are on version 6.2.8 or higher, the password for the report server can be input in the database instead of the property file. The database value is REPORTCUSTOM.PASSWORD.

D. Next, depending on your External Reporting System, you may need to pass additional property values from Maximo. To do this, you can add more property settings to your maximo.properties file. For example, assume a root folder name for the External Reporting System must be passed. This new property value must be added with the prefix mxe.report.custom so it is picked up by Maximo. Therefore, the new property value would be: mxe.report.custom.rootFolder

E. When this information is input, your maximo.properties file will look something like the file shown below. When you have verified that the information is correct, rebuild and redeploy your maximo.ear file. //----------------------------------------------------------------------------// Properties for MXES integration with custom reporting tool. // Customer-defined properties may be added by prefixing the property name with "mxe.report.custom". //----------------------------------------------------------------------------// URL of the custom reporting application mxe.report.custom.serverURL=http://ERep:7001/reportApp/customReport.jsp // Password used for logging on to report server administration tool; will be encrypted // before sending to the reporting application. mxe.report.custom.rptServerLogonPass=admin // Root folder name of Report Server mxe.report.custom.rootFolder=maxreports

2. customreport.jsp A. Next, access the customreport.jsp file. This file is located in: <Maximo root>\applications\maximo\maximouiweb\webmodule\webclient\utility The customreport.jsp file shows the relevant information that is always sent from V6 to the report server, and provides instructions on how to access that information. Examples of values in this file that are always passed are: Report File Report Folder Schema Application Name It will be up to you and the external reporting system that you are integrating with to determine if the customreport.jsp file will be used. The intention of this file is to only highlight the information that is passed from V6 to the external reporting system so the receiving portion can determine how it will process this information. These parameters are sent from a hidden form post from V6 to the External Report Server. Below is a table listing Standard Values passed as request parameters from V6. Report File Name Report Description Report Folder Report Type V6 User Name V6 Password Database User Name Database Password Schema V6 Where Clause User Org User Site App Main Table App Name Language Code Locale Users Local Timezone Report Server URL Report Server Password Security_analysis.rep BI Security Analysis Report SECURGROUP SECURGROUP Wilson See encryption section below Maximo See encryption section below Maximo ((independent = 1)) EAGLENA BUFFALO MAXGROUP SECURGROUP EN EN_US EST http://144.23.45:8090/oraclebi See encryption section below

3. Password Encryption V6 always encrypts the following values before being sending them to the External Reporting System: Maximo Password Database Password Report Server Password It is up to you to determine what security will be implemented on the External Reporting System. If you choose to use any of the passwords sent from V6, the values must be decrypted in the web application. The customreport.jsp file provides examples of how to do so. The decryption requires a V6 class file, CypherPlusBase64.class. This file must be made available to the receiving web application. This file is located in: <Maximo Directory> \applications\maximo\businessobjects\classes\psdi\util An example of where it could be placed is <web application directory>WEB-INF\classes\psdi\util.

Registering and Running ERI Reports in Maximo

After enabling the ERI, the Report Administrator needs to register each external report that will be accessed from Maximo. To do this, the Administrator accesses the V6 Report Administration application. The following information is required for every report that will be executed from Maximo: 1. Report File Name: This is the file name of the report, used by the external report server to identify the report to execute. The external report system determines the value of this field, and whether or not a file extension must be included.

2. Report Description: This is the description of the report as it appears to the user within the V6 applications. 3. Report Run Type: For this integration, the report run type must always be CUSTOM.

4. Application: This is the V6 application where the report will be accessed from.

5. Report Folder: The Report Folder is the folder name where the report is kept in the external report server. This field defaults to the application folder name. With the out of the box Version 6 implementation, report folders were created on the report server to correspond to each of the applications that had reports. Depending on your report server and setup, you may or may not want to set it up this way. 6. Detail?: The Detail Field can be enabled to prevent the user from running the report against more than 200 records in an application. Preventing queries like this can prevent negative performance impacts.

An example of an external report registration is shown below.

Notes: A. There is no validation on any of these fields to the report server. B. Other values in the Report Details Section are not applicable to Reports from External Reporting Systems. These include: No Request Page Attach Documents Toolbar Location, Toolbar Image and Toolbar Sequence. These fields are only applicable to the embedded reporting tool in Version 6.

10

Parameters: In addition to enabling the application query to pass to the external system, the ERI also enables external reports to include both bound and unbound parameters. Bound parameters are parameters that have either a relationship to the applications main table or exist via a maxrelationships. Unbound parameters do not have any relationships to the applications main table and they do not exist via a maxrelationship. In the custom work order report above, an example of a Bound Parameter would be status (WORKORDER.STATUS). An example of an Unbound Parameter would be Inventory Carrying Cost Percentage. Inventory Carrying Cost Percentage is unbound as there is no relationship between that variable and the Work Order Tracking Application. If a parameter is bound, its value will be included in the Maximo Where Clause that is passed to the report. If a parameter is unbound, its value will not be included in the Maximo Where Clause. Additionally, a report can execute against both Bound and Unbound Parameters and use the Maximo Where Clause. To enable this functionality, select the flag Use Where Clause in the Report Details Section of Report Administration. In the example above, no parameters have been defined for this report, so it will execute against the Current/Selected/All Record Set defined in the application. Finally, note it is the responsibility of the client to manage the types of report parameters used. For more information on the report parameter fields, reference Chapter 6 in the Report Administration and Development Guide.

11

Once the external report and any of its parameters have been registered, the Report Administrator must generate the request page for the report. This is done by clicking on the Generate XML on the Report Tab button. When this has been done, a message will display toolbar saying the Request Page has been generated.

The custom report is now available to users from the Work Order Tracking application. To illustrate how this will work, go to the Work Order Tracking application. Enter a query. In the example below, a query was executed and 18 records were selected..

To run the report, the end user selects the Run Reports Action from the menu. A list of all reports that the client has enabled will display. In this example, a variety of reports are enabled. The user selects his custom report.

12

Its report request page is displayed. Notice that the Schedule and Email tabs do not display for the custom report type.

The user then clicks Submit. Version 6 then passes the selected record set of 18 work order records to the External Reporting System. A separate browser session is opened, and the external report displays using the selected record set.

13

4. Additional Details on ERI Security 1. There are 3 Levels of Report Security: a. Does the end user have access to Run Reports? (Set in Maximo's Security Groups application) b. What specific reports can the end user run? (Defined in the external reporting system) c. Once the user runs the report, what data will he see? (Passed from V6 to the Report System via the report where clause. The report where clause includes the V6 MBO set for security.) 2. Security levels A and C will be applied to the Version 6 ERI but not Report Level Security (Level B.) V6 will display all reports registered to a specific application it will not do any filtering for specific user or group access. This means that if you have six custom ERI reports registered to the Work Order Tracking application all users who have access to the Work Order Tracking application and who have run report access will see all six custom ERI reports.

14

Report Functionality Not Supported The table below details the report features that are not enabled or supported in the V6 ERI: Reporting Functionality Not Enabled/Supported Version 6 Out of No ERI Reports will be delivered with Version 6. the Box Reports Report Level Security Filtering for specific user or group access will not be enabled. All reports registered to the specific application will be displayed to all Version 6 users. Configurations of multiple Maximo servers to multiple External Report Servers are not supported Previously executed reports will not be available for display within the Version 6 applications Scheduling of Reports from the Version 6 report request page in the application will not be enabled. Emailing of Reports from the Version 6 report request page in the application will not be enabled. This subtab is not enabled for the external reporting systems. Direct Access to external reports from the Version 6 applications toolbar will not be enabled. Direct Print with Attachments to external reports from the Version 6 applications toolbar will not be enabled. The visibility and ability to update the external reporting systems report titles and labels within the Version 6 Report Administration application will not be enabled.

Multi Server Configurations View Reports

Schedule Reports Email Reports Queries Quick Toolbar Access Attached Documents Report Label Features

15

(5) Frequently asked questions 1. What version of Maximo 6 enables this functionality? The integration is available beginning with Maximo 6.1. 2. Can I use both multiple reporting types? Yes. You can utilize the Version 6 embedded reports, along with custom reports developed in an external reporting system. This configuration is supported; however it is strongly recommended that the Maximo Application Server, Database, embedded Report Server and External Report Server are separated. 3. Yes. Are Oracle, Sql Server and DB2 Databases supported in this integration?

4. Are there any hardware recommendations? Yes. For best performance, it is recommended that your configuration contain dedicated servers for the (1) Application Server (2) Report Server and (3) Database Server 5. What types of Product Platforms are supported in this integration? The specific product platforms that the External Report System supports will most likely vary from those of Maximo 6. Therefore, it is the clients responsibility to use platforms that are supported by both Maximo and their external Report System. 6. Is ERI the only option if a different reporting tool is utilized? No. Version 6 runs on an open database systems (Oracle/ MS SQL Server), and customers can bypass the integration, and run their reporting tool of choice directly against the Version 6 database.

16

Revision History July 2011 (1) Updated with additional notes and diagrams, and also for additional information including new method of password enablement in Version 6.2.8 (2) Updated document file name to remove spaces

17

Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

Trademarks IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be

18

trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at Copyright and trademark information at www.ibm.com/legal/copytrade.shtml. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both

19