Business Service Manager

Transcription

1 Business Service Manager Installation Guide Release 11.7

2 Please direct questions about Business Service Manager or comments on this document to: APM Customer Support FrontLine Support Login Page: Copyright 2011 Compuware Corporation. All rights reserved. Unpublished rights reserved under the Copyright Laws of the United States. U.S. GOVERNMENT RIGHTS-Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in Compuware Corporation license agreement and as provided in DFARS (a) and (a) (1995), DFARS (c)(1)(ii) (OCT 1988), FAR (a) (1995), FAR , or FAR (ALT III), as applicable. Compuware Corporation. This product contains confidential information and trade secrets of Compuware Corporation. Disclosure is prohibited without the prior express written permission of Compuware Corporation. Use of this product is subject to the terms and conditions of the user's License Agreement with Compuware Corporation. Documentation may only be reproduced by Licensee for internal use. The content of this document may not be altered, modified or changed without the express written consent of Compuware Corporation. Compuware Corporation may change the content specified herein at any time, with or without notice. All current Compuware Corporation product documentation can be found at Compuware, Gomez, Private Enterprise, Network Monitoring, Server Monitoring, Vantage for Java and.net Monitoring, VantageView, and FrontLine are trademarks or registered trademarks of Compuware Corporation. Adobe Reader is a registered trademark of Adobe Systems Incorporated in the United States and/or other countries. All other company and product names are trademarks or registered trademarks of their respective owners. Build: November 5, 2011, 12:40

3 Contents Contents Introduction Installation Guide Overview Who Should Read This Guide Organization of This Guide Related Publications Customer Support Information Information to Provide to Customer Support Documentation Conventions Chapter 1 Business Service Manager Architecture Chapter 2 System Requirements Compatible Gomez Solution Releases with Business Service Manager Server Hardware Requirements VMware Supported Environments Business Service Manager Deployment Considerations Load-Balanced Configurations Operating System, Application Server, Database and Java Requirements Supported Platforms Java Requirements Supported Application Servers Supported Databases Supported Browsers Requirements for Client-Only Installation Supported Platforms for the Configuration Client Java Requirements Chapter 3 Database Prerequisites Estimating Database Size Requirements Backing Up the Current Database Configuring the Database Microsoft SQL Server Creating Databases in SQL Server

4 Contents Enabling TCP/IP for SQL Server Configuring Authentication for SQL Server Setting up Windows Authentication to SQL Server Setting up Windows Authentication When Service Model Server, Dashboard and SQL Server are on Different Machines Setting up Windows Authentication When Service Model Server, Dashboard and SQL Server are on Same Machine Remote Connections to SQL Server 2008 R2 Require Configuration SQL Server Database Must Have Case-Insensitive Collation Oracle Database Creating a Business Service Manager Oracle User IBM DB DB2 JDBC Driver Requirement Use UTF-8 as a Code Set DB2 Database Must Have a Buffer Pool DB2 Tablespace DB2 Management Mode DB2 User Privileges DB2 Group Privileges DB2 Schema Requirement DB2 Transaction Logs DB2 Timeout Parameters DB2 JDBC Listener Database Connection Properties Microsoft SQL Server Database Properties Oracle Database Properties IBM DB2 Database Properties Verifying the Database Chapter 4 Installation Prerequisites User Account License Port Settings Configuration and Log Files System Clock Settings Disk Space Issues Chapter 5 New Installations The Installation and Configuration Process Installing Components on Separate Servers Installing Multiple Business Service Manager Instances on the Same Machine Windows Standard Installation Client Installation Custom Installation Windows Command-Line Installation Installing on UNIX UNIX Remote Silent-Mode Install Without X Server

5 Contents Properties File for Command-Line Installation Installing on Linux Chapter 6 Post-Installation Tasks UNIX Permissions Configuring the Application Server Apache Tomcat Configuration Generating Keys and Certificates Configuring the Apache Tomcat Server Configuring the Java Runtime Environment Restart WebSphere Configuration Prepare for Deployment of the Context-Sensitive Help Provider Prepare the Application WAR Files Prepare the WebSphere Runtime Environment Deploy the WAR Files to WebSphere WebLogic Configuration Prepare for Deployment of the Context-Sensitive Help Provider Prepare the Application WAR Files Preparing the WebLogic Domain Deploy the WAR files to the WebLogic Domain Database Archiving Options Archiving Plugin Configuration Checking Directory Contents Starting and Stopping the Service Model Server Starting the Service Model Server on UNIX Shutting Down the Server on UNIX Starting the Service on Windows Stopping the Service on Windows Starting the Configuration Client Starting on UNIX Starting on Windows Login Starting the Web Interface Adaptor and Interface Settings Sending MAPI Mail for Notifications Chapter 7 Upgrading and Migrating Business Service Manager to Release Upgrading from 11.5.x to Migrating from Release Migration Prerequisites Install the New Release Run the Server Migration Utility Migrate Files Migrate the Database Migrating Custom Datablocks to Version Creating a Dashboard

6 Contents Adding a Page Changing a Page Layout Adding and Deleting Datablocks Export Migrate a Custom Datablock Porting an Existing Centauri Datablock into Liferay Dojo Upgrade and Functions, Features, and Widgets Dojo Functions Dojo Features Dojo Widgets Migrate the Event Console Configuration Migrate Page Caching Post-Migration: Using New Service Model Templates Post-Migration: Adding an 11.7 Sys_Vantage Service Model Template into a Migrated Service Model Template Uninstalling Business Service Manager Appendix A Troubleshooting the Gomez Business Service Manager Installation.. Setup Terminates With Exit Code= No Server Connection: Possible License Problem Checking Connectivity to the Database Maximum File Descriptor Count Exceeded Apache Tomcat Default Port Conflicts with Some Services Appendix B Database Table Partitioning and Data Compression Overview - Support for Database Table Partitioning and Data Compression Customizing Table Partioning and Data Compression Customizing IBM DB2 Database Data Compression Customizing Data Compression - New IBM DB2 Database Customizing Data Compression - Existing IBM DB2 Database Customizing Microsoft SQL Server Table Partitioning and Compression Customizing Partitioning and Compression - New Microsoft SQL Server Database. Customizing Partitioning and Compression - Existing Microsoft SQL Server Database Customizing Oracle Table Partitioning and Compression Customizing Partitioning and Compression - New Oracle Database Customizing Partitioning and Compression - Existing Oracle Database EventDatabaseListener.xml Settings for Database Table Partitioning and Data Compression Relating Database Table Partitioning to Database Purging Index

7 INTRODUCTION Installation Guide Overview This installation guide describes how to install Business Service Manager and its components in your environment. In addition to installation procedures, it provides information about system requirements, application server configuration, post-installation settings, and migration. This guide does not contain reference or usage information. You can find that information in the documents installed with Business Service Manager and the online help. For more information, see Related Publications [p. 8]. Who Should Read This Guide This manual is written for the administrator, application manager, or any other individual who installs and administers Business Service Manager and related components. Organization of This Guide This Installation Guide contains the following chapters: Business Service Manager Architecture [p. 13] Describes the product architecture and its functional components. System Requirements [p. 17] Describes the environments supported for Business Service Manager, and provides sample configurations for estimating memory and other requirements. Database Prerequisites [p. 25] Describes configuration details and connection properties for the supported databases. Installation Prerequisites [p. 53] Describes information that must be provided and tasks that must be performed before beginning the Business Service Manager installation. 7

8 Introduction New Installations [p. 59] Provides instructions for performing new installations. Post-Installation Tasks [p. 75] Describes the configuration tasks that must be performed after installation is completed, including configuring the application server. Also describes how to start up the Gomez Business Service Manager components. Upgrading and Migrating Business Service Manager to Release 11.7 [p. 93] Provides information and Instructions for migrating Business Service Manager from the previous release. Troubleshooting the Gomez Business Service Manager Installation [p. 117] Describes possible solutions for issues that may occur after installation. Database Table Partitioning and Data Compression [p. 121] Describes the default configuration for table partitioning and data compression in the Business Service Manager database, and provides instructions for customizing the settings in a new or existing database. Related Publications Online help is accessible from the interface menu and by pressing [F1]. The following documents are provided in PDF format: Business Service Manager Release Notes This document contains information about the release: New feature descriptions. List of supported platforms, databases, hardware, adaptors, and browsers. Known issues. Troubleshooting information. Contains the following information: Preparation for the Business Service Manager installation, including requirements for databases. The installation procedure. Post-installation procedures and checks. Upgrade and/or migration procedures from a previous release. It also includes notes on typical system configurations, which may helpful in assessing your setup and installation. Business Service Manager Administration Guide Details the actions your system administrator may need to take to manage data and maintain the Service Model server. It outlines data backup and restoration procedures, requirements for user privilege configurations, multiple server configurations, and Web server setup requirements. 8

9 Introduction Business Service Manager Service Model User Guide Contains the following information: Discussion, with examples, of a best-practices approach to developing and maintaining a Service Model. Supporting instructions for performing basic setup tasks for the Service Model, Service Model Templates, data connections, and services. Business Service Manager Data Collection User Guide Contains the following information: Information how to use adaptors to collect data from Gomez solutions, infrastructure management and service desk applications, and protocol and standards tools. How to set up polling schedules (collection of data). Setting up Message Translators to filter data being sent to the Service Model. Business Service Manager Event Management User Guide Describes the Event Management system, including information on: Notifications accessed through the Configuration Client and the Dashboard Web interface. Event Console accessed through the Configuration Client and the Dashboard Web interface. Introduces the Event Management Database Message Filter/Translator. Business Service Manager Dashboard and Datablocks User Guide Contains information about creating and editing dashboards and the datablocks they contain. It also includes information about the types of data displayed in the datablocks, customization, and producing service reports. Business Service Manager Developer Reference Contains the following information on how to customize Business Service Manager using industry standard scripting languages, including: Basic script editor functions available from the Configuration Client. Use of the Command Line Interface (CLI). Information on the Expression Language and JavaScript Expressions. Business Service Manager Dashboard SDK User Guide Technical guide for an advanced user when customizing the main interface for specific use cases. It provides details for configuring and programming new dashboards for end users, so that new screens are presented in the form they require. Business Service Manager Connection Manager SDK User Guide Technical information for an advanced user or developer on customizing and programming adaptors. It provides details of supported event formats and the various protocols associated with connections. Business Service Manager Service Model SDK User Guide Technical guide for a developer to customize and extend the Service Model using Java or JavaScript programming methods. 9

10 Introduction Customer Support Information FrontLine Support Web Site You can access information for Compuware products via our FrontLine support site. You can review frequently asked questions, read or download documentation, access product fixes, or your questions or comments. The first time you access FrontLine, you are required to register and obtain a password. Registration is free. To access FrontLine, log in to Select your product from the Product Support dropdown list. You can also access product User Communities from After you log in, select Compuware User Groups and select your product line. Contacting Customer Support Phone USA and Canada: or All other countries: Contact your local Compuware office. Contact information is available at Web You can report issues via the Report and Track Calls tab on the FrontLine home page. NOTE Please report all high-priority issues by phone. Mail Customer Support Compuware Corporation One Campus Martius Detroit, MI Corporate Web Site To access Compuware's site on the Web, go to The Compuware site provides a variety of product and support information. Information to Provide to Customer Support Provide Customer Support with as much information as possible about your environment and the circumstances that led to the difficulty. Please be ready to provide: Your client number. This number is assigned to you by Compuware and is recorded on your sales contract. The name, release (version), and build number of the Gomez product and its components. This information is displayed when you select the About command from your product's Help menu. The name and release are also on the covers of the product documentation. 10

11 Introduction Environment information, such as the operating system and release (including service pack level) on which the product is installed, memory, hardware/network specifications, and the names and releases of other applications that were running. Problem description, including screen shots. Exact error messages, if any (screen shots recommended). Whether the problem is reproducible. If yes, sequence of steps to reproduce the problem. If not, a description of the actions taken before the problem occurred. A description of the actions that may have been taken to recover from the difficulty, and their results. Log file(s) from the component(s) affected by the problem. Compuware values your comments and suggestions about the Gomez products and documentation. Your feedback is very important to us. If you have questions or suggestions for improvement, let us know. Documentation Conventions The following font conventions are used throughout documentation: This font Bold Citation Documentation Conventions [p. 11] Fixed width Fixed width bold Fixed width italic Menu Item Screen Indicates Terms, commands, and references to names of screen controls and user interface elements. Emphasized, text, inline citations, titles of external books or articles. Links to Internet resources and linked references to titles in Compuware documentation. Cited contents of text files, inline examples of code, command line inputs or system outputs. Also file and path names. User input in console commands. Place holders for values of strings, for example as in the command: cd directory_name Menu items. Text screen shots. Code block Blocks of code or fragments of text files. 11

12 Introduction 12

13 CHAPTER 1 Business Service Manager Architecture Business Service Manager provides a modular architecture that enables it to be scalable and to provide maximum deployment options. All features use industry standard protocols such as JDBC, JMX, and XML to ensure interoperability and to provide lines of development into the future. The Service Model and related components comprise a Java-based and platform-independent application. The following figure illustrates the overall architecture, showing functional components in their deployment context. Deployment components are outlined in the figure, and are described below. 13

14 Chapter 1 Business Service Manager Architecture Figure 1. Gomez Business Service Manager Technical Architecture Service Model server The Service Model server is a standalone Java application that runs the Service Model and other key components. Connection Manager The Connection Manager, a server subcomponent of the Service Model server, is often deployed separately on its own machine. It is responsible for connecting the Service Model server to external devices. These interactions can be bidirectional where the data source supports that interaction. For example, two-way helpdesk systems may have Business Service Manager collecting data on ticket statuses as well as creating tickets for service management problems. Database Environment Business Service Manager stores all of its data and the major parts of its configuration in its two databases one for the Service Model, and another for the Dashboard. The performance of the database is critical to the overall performance so a separate database server is often recommended. 14

15 Chapter 1 Business Service Manager Architecture Application Server A J2EE application server runs the Web (Dashboard) application. It handles the real-time service visualization and reporting. Most end users interact with Business Service Manager using this interface. Configuration Client Business Service Manager is a client/server application that allows remote configuration and visualization of data. Service Model and dashboard components can be deployed on different machines for large-scale organizations. For example, the application server and the database would typically be hosted on separate machines. Business Service Manager also supports failover mode to ensure constant operation and processing of data. Typical architecture for a large site with failover support might include a Connection Manager server managed by the customer internally, collecting information from the local infrastructure; and a second Connection Manager server operated by a service provider that is responsible for managing some servers. During normal operation, both Connection Manager servers feed the primary Service Model server, which stores data and configuration in the database. 15

16 Chapter 1 Business Service Manager Architecture 16

17 CHAPTER 2 System Requirements This chapter contains information on the operating system platforms, JREs, application servers, databases, and browsers supported by this release of Business Service Manager. This chapter also includes information on what Gomez solutions are compatible with this release. Compuware strongly recommends using Microsoft Windows Server bit, SQL Server 2008 and Tomcat application server. Individual component requirements follow. Compatible Gomez Solution Releases with Business Service Manager 11.7 Business Service Manager Release 11.7 is compatible with the following Gomez (formerly Vantage) solutions: Vantage Solution Gomez Real-User Monitoring Data Center Vantage for Java and.net Monitoring Gomez Synthetic Monitoring Private Enterprise Gomez Server Monitoring Gomez Network Monitoring Supported Release(s) 11.6, Central Analysis Server (CAS) must be on release 11.6 or , 11.5, 11.7 CAS must be on release 11.6 or , 11.5, x CAS must be on release 11.6 or Server Hardware Requirements A Business Service Manager configuration consists of three main components: 17

18 Chapter 2 System Requirements The Service Model server and Configuration Client. The application server. (The default is Apache Tomcat, installed with Business Service Manager). For more information, see Supported Application Servers [p. 22]. The database. For more information, see Supported Databases [p. 22]. Each of these components, in addition to the Connection Manager (a subcomponent of the Service Model server), can be installed separately on its own physical or supported virtual server to distribute load. The same basic server hardware and software requirements apply when deploying these components separately. Hardware requirements for installing the Service Model server vary with the system configuration. Factors that affect requirements include the database size and configuration, and whether services are installed on a single machine or distributed to separate servers. Compuware recommends any physical or vserver supporting Microsoft Windows 2003 Server or 2008 Server, with the following hardware specifications (or equivalent) as a minimum requirement. Table 1. Minimum Hardware Requirements Hardware Component CPU Memory Hard drive Specification 2 x Quad Core Intel Xeon 5450, 3.00-GHz processor, 1333-MHz FSB 32-GB 667-MHz Dual Ranked DIMMs 6 x 146-GB Hot Plug 2.5 SAS, 10-Kb RPM Hard Drive (RAID 1+0 configuration) Specific systems have special needs and requirements. In addition to considering these guidelines, you should make your own assessment of your system and, if necessary, consult Compuware Customer Support. VMware Supported Environments All of the Business Service Manager server components can be installed on VMware virtualized environments, including VMware Workstation 7.x+ and vsphere 4.x and 5.x. Ensure that the virtual environment provides at least the minimum specifications described for physical servers and you factor in deployment considerations in resource allocation. For more information, see Server Hardware Requirements [p. 17] and Business Service Manager Deployment Considerations [p. 18]. Business Service Manager Deployment Considerations Performance Factors System memory is a significant factor for Business Service Manager performance. As the Service Model size and event-processing rates increase, more memory is required. 18

19 Chapter 2 System Requirements There is a strong correlation between concurrent users and performance: the more users on the system, the slower the Dashboard response. With a large number of Dashboard users, a twoor three-tier deployment is essential, with the application server on its own server. The size of the Service Model and the memory settings for the statistics cache and service cache have the greatest impact on Web server memory. To optimize performance, balance these settings with the JVM heap memory. When you expect heavy event processing, it is recommended that you install Business Service Manager components in a two-tier or three-tier environment. In a two-tier environment, the Service Model server should be installed on the same machine as the database, and the application server should be on a separate machine. A three-tier system provides the best performance to process events for a medium to large Service Model and a large number of concurrent users. Load Estimates Use the following table of example configurations to determine the Service Model server requirements for the expected load. Table 2. Example Service Model Configurations Services Service Model Details Concurrent Users Number of Tiers Recommended Service Model Server Memory Recommended Application Server Memory 25, applications GB 5 GB 45 locations 4,100 transactions 25, applications GB 8 GB 45 locations 4,100 transactions 25, applications GB 8 GB 45 locations 4,100 transactions 50, applications GB 10 GB 40 locations 8,000 transactions 80, applications GB 10 GB 80 locations 19

20 Chapter 2 System Requirements Services Service Model Details Concurrent Users Number of Tiers Recommended Service Model Server Memory Recommended Application Server Memory 14,200 transactions The table does not contain database estimates. Database memory must be tuned on a case-by-case basis according to the database system and the specific needs for data storage and retrieval. Load-Balanced Configurations Single-Tier In a single-tier configuration, the Service Model server, the application server, and the database server all run on the same machine. A single-tier configuration should be used only when you expect the service load to remain small. For more information, see Example Service Model Configurations [p. 19]. Server Service Model server Application server Database Two-Tier A two-tier configuration is appropriate when you expect that the load will not increase beyond moderate levels. Server1 Service Model server Database Server2 Application server Three-Tier A three-tier configuration optimizes scalability. Server1 Service Model server Server2 Application server Server3 Database server 20

21 Chapter 2 System Requirements Operating System, Application Server, Database and Java Requirements Supported Platforms The Supported Operating Systems table identifies the hardware and operating system platforms on which the Business Service Manager components can be deployed. Table 3. Supported Operating Systems Operating System Windows 2008 Server Windows 2008 Server R2 64-bit Windows 2003 Server 32-bit and 64-bit Red Hat Enterprise Linux 4.0 and bit and 64-bit Solaris 9 and bit and 64-bit IBM AIX 5.3 and bit Comments The 64-bit Windows 2008 Server is the recommended platform for Business Service Manager. Compuware strongly recommends using the same platform as used for the Central Analysis Server. All editions. Only supported on certified hardware. You must install your own JRE. Java 1.5.0_14 is required. Operating system patches may be required for the particular version of the JRE. Solaris is not supported for the Configuration Client. AIX is not supported for the Configuration Client. JRE with service refresh SR12 FP3 is required. Java Requirements The Service Model server supports JRE version 1.5 and 1.6. To start the Configuration Client through the Dashboard, using Java Web Start, you must have Java Web Start version 1.6 (6.0). On 64-bit environments, use the 32-bit JRE. The Configuration Client supports only JRE version 1.5. Each platform must have all patches installed to bring the system up to date and to enable it to run the required version of the JRE. Obtain details from the vendor. 21

22 Chapter 2 System Requirements CAUTION If you are running UNIX on a 64-bit platform, you must have the 64-bit JRE. Mixed mode is not supported. For the latest requirements, or if you have difficulty identifying or locating the relevant patches, contact Compuware Customer Support. Supported Application Servers The following table lists the supported application servers. Table 4. Supported Application Servers Application Server Apache Tomcat IBM WebSphere Oracle WebLogic Version Supported 6.x 6.1, with Fix Pack 21 or higher 10.x Notes Apache Tomcat is the default Web application server installed with Business Service Manager and is the recommended application server. Some services that work with Business Service Manager (e.g. HP OpenView) may use port 8080, which is also the default Tomcat port. If you use these services, you may need to configure Tomcat to use an alternative port. For more information, see WebSphere Configuration [p. 79]. Page caching is not supported. For more information, see WebLogic Configuration [p. 83]. Page caching is not supported. Supported Databases The following table identifies supported databases and JDBC drivers. Table 5. Supported Databases and Drivers Database Supported Versions JDBC Driver Comments Microsoft SQL Server R2 jtds 1.2 Supplied with Business Service Manager. Microsoft SQL Server 2008 Enterprise Edition is the recommended database for Gomez. Table partitioning and data compression features require Enterprise or Developer Edition. See 22

23 Chapter 2 System Requirements Database Supported Versions JDBC Driver Comments Microsoft SQL Server 2005 jtds 1.2 Supplied with Business Service Manager. Table partitioning features require Enterprise Edition or Developer Edition. Data compression is supported only in SQL Server See Oracle 10g 10.2 (10g Release 2) Supplied with Business Service Manager. See 11g Oracle Grid 11g Supplied with Business Service Manager. See IBM DB2 8.2 (fixpack 4) Obtain from DB2 installation package. For more information, see DB2 JDBC Driver Requirement [p. 33]. Also see DB2 is not supported for the Dashboard page caching feature. For more information, see Page Caching in the Business Service Manager Dashboard and Datablocks User Guide. Supported Browsers The following table lists the supported Web browsers. Table 6. Supported Browsers Browser Mozilla Firefox Microsoft Internet Explorer Version 3.x , 8.0, 9.0 To view some reports, you must have PDF and SVG viewers, which can be downloaded from There are known issues with specific Web browsers. Java 5 (formerly 1.5) is supported for browser applets in this release of Business Service Manager. 23

24 Chapter 2 System Requirements Requirements for Client-Only Installation You can install the Configuration Client separate from the Service Model server. This section describes the system requirements and supported environments for a standalone Configuration Client. Supported Platforms for the Configuration Client The Supported Operating Systems table identifies the operating system platforms on which the Configuration Client can be deployed. Table 7. Supported Operating Systems for the Configuration Client Operating System Windows XP Professional 32-bit Windows 2003 Server 32-bit and 64-bit Windows 2008 Server 64-bit Comments SP2 required. All editions. The 64-bit Windows 2008 Server is the recommended platform for Business Service Manager. Windows Vista Enterprise Windows 7 Red Hat Enterprise Linux 4.0 and bit and 64-bit Only supported on certified hardware. Java Requirements The Service Model server supports JRE version 1.5 and 1.6. To start the Configuration Client through the Dashboard, using Java Web Start, you must have Java Web Start version 1.6 (6.0). On 64-bit environments, use the 32-bit JRE. The Configuration Client supports only JRE version 1.5. Each platform must have all patches installed to bring the system up to date and to enable it to run the required version of the JRE. Obtain details from the vendor. CAUTION If you are running UNIX on a 64-bit platform, you must have the 64-bit JRE. Mixed mode is not supported. For the latest requirements, or if you have difficulty identifying or locating the relevant patches, contact Compuware Customer Support. 24

25 CHAPTER 3 Database Prerequisites If you are performing a new installation of Business Service Manager on a Windows server, Compuware recommends using a SQL Server database (preferably SQL Server 2008 Enterprise Edition). The Business Service Manager uses two databases in release 11.7 (one for the Service Model server, the other for the Dashboard), so you should create two databases. You should review the information in Estimating Database Size Requirements [p. 25] to ensure your host has necessary resources before installing Business Service Manager. The databases must be configured before you install Business Service Manager. During installation, you will be prompted to identify the host, port number and login information for a user with sufficient administrative rights. For more information, see Configuring the Database [p. 26]. The configuration instructions are also useful if you need to change database user or account settings after Business Service Manager is installed. When using SQL Server, the database will be initialized with table partitioning and data compression enabled. The default partitioning and compression setup is matched to a default data purging configuration in the Configuration Client. For more information, see Database Table Partitioning and Data Compression [p. 121]. Estimating Database Size Requirements The Service Model server database will require much more disk space than the Dashboard's. The amount of space the Service Model server database uses is affected by many factors, including settings not specified in the product installation. Therefore, only estimates of required disk space can be provided. Configuration changes to database software or event providers can change the requirements significantly. Business Service Manager subsystems have different requirements. The following table provides guidelines for calculating server database size. The guidelines specify the most significant factors and provide a simplified formula for each component. 25

26 Chapter 3 Database Prerequisites Table 8. Server Database Size Calculation Guidelines Subsystem Event Management Notifications Service Model Out of Order Data processing Significant Factors Number of events Number of alarm events Number of services, polling interval, and statistics generation interval Number of service checkpoints Formula 1 MB + ((number of stored events) * 1.5 KB) (number of alarm events) * 0.5 KB In normal cases, the number of alarm events is not significant; therefore, the space required is negligible. (number of services) * 20 KB With default settings, the Service Model server database requires approximately 20 KB of disk space per Service Model service. This estimate is a minimum requirement. Factors such as polling schedules, data retention period, statistics options, and the number of updates to the service configuration will significantly increase the requirement. Each service checkpoint requires approximately 35 KB. Assume the following details: 1,000 services MaxRollbackTime='7 days' CheckpointInterval='30 min' 8 checkpoints * 7 days * 1000 services = 336, KB * 336,000 = 11,760,000 KB = ~11.5 GB Backing Up the Current Database Before installing the Business Service Manager, create a backup copy of your existing database as a rollback option, as well as to ensure that database integrity is maintained during the installation. 1. Export your current database. 2. Create a new database schema for your existing installation. 3. Import the database into your new schema. Configuring the Database Before installing Business Service Manager, you must initialize and configure the database to be used for the system. After initial installation is complete, you may need to verify details to ensure that Business Service Manager is working correctly with the database. The following topics provide setup details for the supported databases: 26

27 Chapter 3 Database Prerequisites Microsoft SQL Server [p. 27] Oracle Database [p. 31] IBM DB2 [p. 32] After installation, if you want to modify the database settings used by the system (like authentication), you can run the Business Service Manager Setup Wizard by running Setup.exe in BSM_HOME/bin. IMPORTANT For security purposes, when permissions must be granted, they should be granted to groups or roles, not to individual user accounts. No permissions on system objects should be granted to the Guest user or Public role. Microsoft SQL Server For Business Service Manager to work correctly with Microsoft SQL Server, the TCP/IP connection method must be enabled on the SQL Server instance, a SQL user must be associated with the SQL Server instance, and Business Service Manager must have complete control of the SQL Server database. When installing Business Service Manager, new database(s) will be initialized with table partitioning and data compression enabled. The default partitioning and compression setup is matched to a default data purging configuration in the Configuration Client. It is also possible to enable partitioning and compression on an existing database. For more information, see Database Table Partitioning and Data Compression [p. 121]. Creating Databases in SQL Server Create two databases for BSM (one for the Dashboards, the second for the Service Model server) in Microsoft SQL Server through the Microsoft SQL Server Management Studio. 1. Connect to Microsoft SQL Server through Microsoft SQL Server Management Studio, as a Microsoft SQL Server user who has permission to create a database. 2. Right-click the Databases node and select New Database. 3. Enter a unique database name. 4. Set the database owner to the BSM user. 5. Edit the Primary Filegroup Database files default specifications as follows: For Initial Size, enter 20 GB. For Autogrowth, enter 2 GB. For the Log, for Initial Size, enter 200 MB. 6. Click OK. 27

28 Chapter 3 Database Prerequisites Enabling TCP/IP for SQL Server Business Service Manager always connects to Microsoft SQL Server using a TCP/IP connection, even if the database and Business Service Manager are on the same host. SQL Server is not shipped with TCP/IP enabled. Perform the following steps to enable TCP/IP connections on the server. 1. Connect to the server using the SQL Server Configuration Manager. 2. Expand the SQL Server Network Configuration tree node. 3. Select Protocols for instance, where instance is the SQL Server instance to which you want Business Service Manager to connect. 4. From the context menu of the TCP/IP protocol node, select Enabled. 5. Restart the SQL Server instance for the changes to take effect. Configuring Authentication for SQL Server Business Service Manager can use SQL Server authentication when connecting to Microsoft SQL Server. By default, SQL Server only enables Windows Authentication Mode. Perform the following steps to enable SQL Server authentication. 1. Connect to Microsoft SQL Server through Microsoft SQL Server Management Studio, as a Microsoft SQL Server administrator. 2. Select Properties from the context menu of the desired server. The Server Properties dialog box appears. 3. Select the Security option. 4. In the Server authentication section, select the SQL Server and Windows Authentication mode option. 5. Restart the server for the settings to take effect. The following figure shows the required settings. 28

29 Chapter 3 Database Prerequisites Figure 2. Enabling SQL Server Authentication NOTE If the database is on a separate server from the Service Model server, use the Setup Wizard to define the Windows Authentication Account and password to configure services for the Service Model and Dashboard. Setting up Windows Authentication to SQL Server Assuming that your SQL server is configured to use Windows authentication, this security configuration option is available to you when configuring Business Service Manager. There are different procedures depending on how you plan to implement BSM: Setting up Windows Authentication When Service Model Server, Dashboard and SQL Server are on Different Machines [p. 30] Setting up Windows Authentication When Service Model Server, Dashboard and SQL Server are on Same Machine [p. 30] NOTE Using a domain ID to configure SQL security as described above is subject to problems resulting from password change. If the service password is not updated when the password for that ID is changed, the service will not start due to a logon failure. 29

30 Chapter 3 Database Prerequisites Setting up Windows Authentication When Service Model Server, Dashboard and SQL Server are on Different Machines Before installing BSM, ensure the host machines where you will install the Service Model server, Dashboards and SQL Server are in the same domain. You will configure the database before installing BSM. 1. Configure SQL Server to allow [domain]\user to have access to both the Liferay (Dashboards) and Service Model server databases. a. In SQL Server Management Studio, expand the Security Logins node and select New Login from the context menu. b. Under Select a page, select General. c. Click Search to find the user needed to populate the Login Name field. Ensure a domain is included. d. Under Select a page, select User Mapping. Select the databases that you created for the Dashboards and Service Model server. Depending on which version of SQL Server you are using, and if you enabled Page Caching, select that database as well. For more information, see Page Caching in the Business Service Manager Dashboard and Datablocks User Guide. For the domain\user, grant db_owner and public role membership for these databases. For Page Caching, grant db_creator membership. e. Click OK to save. 2. Install Business Service Manager, and during database setup, provide the Windows domain\user credentials under Trusted Connection. 3. When installation is complete, stop both the Gomez Reporting Portal 11.7 and Gomez Service Model 11.7 services. 4. Staying in Services, right-click the Gomez Service Model 11.7 to display its properties. 5. Ensure that the user ID and password are correct for the domain\user added during installation. 6. Add the domain\user to the server's Local Administrator group. a. Go to Administrative Tools Computer Management. b. Click Add, enter the domain\user, and click OK to save the properties. 7. Open the Properties for the Gomez Reporting Portal Remove the \VSMUSR_TOMCAT administrator account, and click Add to include the domain\user that you previously used to install services and databases for BSM. 9. Restart both the Gomez Service Model 11.7 and Gomez Reporting Portal 11.7 services. Setting up Windows Authentication When Service Model Server, Dashboard and SQL Server are on Same Machine When you intend to install BSM components and SQL Server on the same machine, you will need to install BSM, and then reconfigure SQL Server for Windows authentication. 1. After BSM installation is complete, stop the Gomez Reporting Portal 11.7 service. 2. In SQL Server, allow [domain]\vsmusr_tomcat to have access to both Liferay (Dashboard) and BSM databases. 30

31 Chapter 3 Database Prerequisites a. In SQL Server Management Studio, expand the Security Logins node and select New Login from the context menu. b. Add the new user, LocalHostName\VSMUSR_TOMCAT. c. Under Select a page, select User Mapping and select the PageCaching, Report_Server_11_7 and the vsm_11_7 databases. The PageCaching database will appear only in SQL Server For the domain\user, grant db_owner and public role membership. d. Click OK to save. 3. Start the Gomez Reporting Portal 11.7 service. Remote Connections to SQL Server 2008 R2 Require Configuration By default, SQL Server 2008 R2 does not support remote connections, so Business Service Manager will not recognize the SQL Server machine during database installation. You can configure this setup manually. See the article remote SQL Server configuration for setup information. SQL Server Database Must Have Case-Insensitive Collation The Business Service Manager SQL Server database must be created with case-insensitive collation to provide functionality to the Service Model server. During the installation, the database setup process will substitute the case-insensitive collation of NVARCHAR columns with a corresponding case-sensitive collation found in the collation mapping file (BSM_HOME\vsm\config\MScollators.properties). If the mapping did not succeed during the setup process, the database setup will be stopped. You would then have to update the mapping file with the entry that reflects the current database collation and the corresponding case-sensitive collation. Oracle Database To use an Oracle database with Business Service Manager, you must grant system privileges on the tablespace. The required system privileges are: CREATE ANY INDEX CREATE SESSION CREATE TABLE CREATE VIEW CREATE SEQUENCE CREATE PROCEDURE ALTER ANY SEQUENCE UNLIMITED TABLESPACE 31

32 Chapter 3 Database Prerequisites NOTE To change user privileges, you must be logged in to the system with administrator rights and the necessary access privileges to the database. Make sure your database version is supported by Business Service Manager. For more information, see Supported Databases [p. 22]. The tablespace name and username for the Business Service Manager database must not contain special characters. When installing Business Service Manager, a new database will be initialized with table partitioning and data compression enabled. The default partitioning and compression setup is matched to a default data purging configuration in the Configuration Client. It is possible to manually revise and implement table partitioning and data compression. For more information, see Overview - Support for Database Table Partitioning and Data Compression [p. 121]. Creating a Business Service Manager Oracle User IBM DB2 Create the Business Service Manager Oracle user by using the create user command. 1. Create the Oracle user. Execute the following command as one line: create user VantageUserName identified by VantageUserPassword default tablespace VantageTablespaceName temporary tablespace TemporaryTablespaceName; For example: create user vantagesm identified by vantagesm default tablespace vantagesmdata temporary tablespace temp; 2. Grant database permissions. Execute the following command as one line: grant create any index, create session, create table, create view, create sequence, create procedure, alter any sequence, unlimited tablespace to NewUserName; 3. Make sure the SQL*Net listener is running on the Oracle database server. You may need to adapt the IBM DB2 database configuration for Business Service Manager to ensure connectivity. Database information Make sure your database version is supported by Business Service Manager. For more information, see Supported Databases [p. 22]. During installation, a new database will be initialized with data compression enabled. It is also possible to enable compression on a existing database. For more information, see Database Table Partitioning and Data Compression [p. 121]. 32

33 Chapter 3 Database Prerequisites NOTE Most of the following DB2 setup options are described using command line functions. Many of these configurations also can be performed using the DB2 Database Creation Wizard or the Control Center. DB2 JDBC Driver Requirement To use DB2, copy the relevant IBM DB2 JDBC driver files into Business Service Manager Java installation area, and add any relevant license files to your CLASSPATH. IMPORTANT It is strongly recommended that you use the JCC driver set provided with Business Service Manager, rather than the Net driver set of files for DB2 operations. 1. Locate the files db2java.zip and db2jcc.jar in the DB2 installation package tree. By default, they are installed in the DB2_Installation/SQLLIB/java directory. 2. Copy both files to BSM_HOME/lib and to BSM_HOME/tomcat/webapps/centauri/WEB-INF/lib. 3. In both locations, rename the db2java.zip file to db2java.jar. For DB2 v8.1.2 and higher, make sure you have correctly installed the relevant licenses for your DB2 installation in BSM_HOME/lib and BSM_HOME/tomcat/webapps/centauri/WEB-INF/lib. The license.jar files may include the following: db2jcc_license_c.jar db2jcc_license_cu.jar db2jcc_license_cisuz.jar Refer to your DB2 documentation to determine the correct file(s) to install for your system, and where they may be copied from. Use UTF-8 as a Code Set If your data will potentially contain Unicode-based characters, choose the UTF-8 code set when specifying the locale for the DB2 database. In the DB2 Create Database Wizard, this option is located on the Region page. DB2 Database Must Have a Buffer Pool The Business Service Manager database must have a buffer pool with a page size of at least 8 KB. If you have or expect large configuration trees, a size of at least 10,000 pages is recommended. Your database administrator may need to review the dimensions recommended above, according to your local requirements. 33

34 Chapter 3 Database Prerequisites To create a database for Business Service Manager, execute the following SQL command as one line: CREATE DATABASE db_name ON drive USING CODESET codeset TERRITORY territory COLLATE USING SYSTEM where db_name is a name no more than 8 characters long that complies with DB2 naming conventions. For example: CREATE DATABASE VSM11 on C: USING CODESET IBM-1252 TERRITORY US COLLATE USING SYSTEM NOTE The default log space used by the database may be too small. If necessary, increase it to 10 primary logs and 30 secondary logs, with a log file size of 1,000 pages. Primary log space is retained; secondary log space is freed when not in use. DB2 Tablespace The Business Service Manager database requires a tablespace created with a page size of at least 16 KB. In DB2, the default page size is 4 KB. To create a tablespace with a page size of 16 KB, you must first create a buffer pool with a page size of 16 KB. If there are large configuration trees, a size of at least 10,000 pages is recommended. 1. To create a buffer pool with a page size of 16 KB, execute the following SQL command as one line: CREATE BUFFERPOOL poolname SIZE NumberOfPages PAGESIZE PageSize For example: CREATE BUFFERPOOL PageEight SIZE 250 PAGESIZE 16K 2. Restart the database so the tablespace assignment to the new buffer pool will take effect. Unless the database is started, any tablespace that is created will use an already active buffer pool of the same page size. 3. To create a regular tablespace, execute the following SQL command as one line: CREATE REGULAR TABLESPACE space_name PAGESIZE page_size MANAGED BY management_mode USING (directory_path) BUFFERPOOL pool_name For example: CREATE REGULAR TABLESPACE VantageSMTables PAGESIZE 16K MANAGED BY SYSTEM USING ('G:\ VantageSMTables\') BUFFERPOOL PageEight 4. To create a temporary tablespace for use by Gomez, execute the following SQL command as one line: CREATE TEMPORARY TABLESPACE tablespace_name PAGESIZE page_size MANAGED BY management_node USING (directory_path) BUFFERPOOL pool_name For example: CREATE TEMPORARY TABLESPACE vantage_tmp_tbl PAGESIZE 16K MANAGED BY SYSTEM USING ('g:\vantagetemptables') BUFFERPOOL PageEight 34

35 DB2 Management Mode The management mode for the DB2 database can be any valid mode in DB2. Connect to the database and, if necessary, assign CREATE TABLE privileges for the login ID. If the default authentication method is used, the login ID must exist on the local operating system. The privileges can be assigned to the user, the group, or both. DB2 User Privileges 1. To assign the required user privileges, execute the following command: GRANT CREATETAB, CONNECT ON DATABASE TO USER user_name For example: GRANT CREATETAB, CONNECT ON DATABASE TO USER Vantage 2. To assign a tablespace with a page size at least 8 KB to the login ID, execute the following command: GRANT USE OF TABLESPACE space_name TO USER user_name For example: GRANT USE OF TABLESPACE VantageSMTables TO USER Vantage Chapter 3 Database Prerequisites DB2 Group Privileges Assign group privileges and tablespace to a group for Business Service Manager. 1. To assign the required group privileges, execute the following command: GRANT CREATETAB, CONNECT ON DATABASE TO group_name For example: GRANT CREATETAB, CONNECT ON DATABASE TO VantageGroup 2. To assign the tablespace to the group, execute the following command: GRANT USE OF TABLESPACE space_name TO USER group_name For example: GRANT USE OF TABLESPACE VantageSMTables TO USER VantageGroup DB2 Schema Requirement A schema with the same name as the login must exist. By default, the schemas are created automatically. If the Create schemas implicitly privilege is disabled, execute the following SQL command: CREATE SCHEMA user_name AUTHORIZATION user_name For example: CREATE SCHEMA Vantage AUTHORIZATION Vantage DB2 Transaction Logs Create a transaction log with at least two primary log files and two secondary log files with a capacity of 40 MB each. Each log file comprises 10,000 pages of 4 KB per page. 35

36 Chapter 3 Database Prerequisites The transaction log must be an archive logging type, with the logretain and userexit parameters set to OFF. To configure the transaction log as needed, execute the following command as one line: UPDATE DB CFG FOR database_name USING logretain OFF userexit OFF logprimary 2 logsecond 2 logfilsiz 10000; BACKUP DATABASE database_name TO transaction_logs_path WITH 1 BUFFERS BUFFER 1024 PARALLELISM 1 WITHOUT PROMPTING; For example: UPDATE DB CFG FOR TESTDB USING logretain OFF userexit OFF logprimary 2 logsecond 2 logfilsiz 10000; BACKUP DATABASE TESTDB TO "D:\DB2\TestDB\Logs\TESTDB\" WITH 1 BUFFERS BUFFER 1024 PARALLELISM 1 WITHOUT PROMPTING; where TESTDB is the name of the database being configured and D:\DB2\TestDB\Logs\TESTDB\ is the location of the transaction logs. DB2 Timeout Parameters The LOCKLIST, MAXLOCKS, and LOCKTIMEOUT settings must be modified for the Business Service Manager database to minimize deadlocks caused by timeouts. Each database has one LOCKLIST. This setting determines the amount of storage to be allocated to locks for all applications currently connected to the database. Each lock uses either 32 or 64 bytes, depending on whether the object concerned has previously been locked: a first lock requires 64 bytes and a subsequent lock on the same object requires 32 bytes. The percentage of the LOCKLIST to be held by one application is determined by the setting for MAXLOCKS, which is a percentage setting for an application. If a lock list runs out of space or the total of locks for a particular application reaches the MAXLOCKS percentage of all the locks it can hold, the system escalates the locks so that row locks are replaced by table locks. This reduces the total number of locks in the list. If the whole lock list is running out of space, a recursive process escalates locking to table sizes for the table holding the highest count of row locks, until MAXLOCKS is no longer exceeded. The following formula is a general guide for setting MAXLOCKS: MAXLOCKS = 100 * (512 locks per application * 32 bytes per lock * 2) / (LOCKLIST * 4096 bytes) The LOCKTIMEOUT setting determines how many seconds an application waits to obtain a lock. A zero (0) setting means the application does not wait for a lock; if no lock is immediately available, a -911 value is returned. If LOCKTIMEOUT is set to -1, the application waits until either a lock is granted or a deadlock occurs. Full details for fine-tuning these parameters can be found at DB2 JDBC Listener The JDBC listener must be running with your Gomez database, using the default port number: for the preferred JCC driver, or 6789 for the Net driver. In Windows, start the service DB2 JDBC Applet Server to use this port. In UNIX, Linux, and AIX, the DB2.jcc driver should start the listener automatically. 36

37 Chapter 3 Database Prerequisites Database Connection Properties The topics in this section provide the connection properties for supported databases. For more information, see Supported Databases [p. 22]. Microsoft SQL Server Database Properties The Microsoft SQL Server Database Properties table describes the connection properties supported by the jtds driver. The URL format for jtds is: jdbc:jtds:sqlserver://server[:port][/database][;property=value[;...]] port The port the database server is listening to. The default is 1433 for SQL Server. database The database name (the JDBC term is catalog), the user's default database if not specified. Table 9. Microsoft SQL Server Database Properties Property user Required, with exceptions as noted password Required, with exceptions as noted TDS cachemetadata Default: false Description Specifies the username for login. When getconnection(string url, String user, String password) is used, you do not need to set this property because it is passed as a parameter. You must, however, set it when using getconnection(string url, Properties info) or TdsDataSource. Specifies the password to use for login. When getconnection(string url, String user, String password) is used, you do not need to set this property because it is passed as a parameter. You must, however, set it when using getconnection(string url, Properties info) or TdsDataSource. Specifies the version of TDS to be used. Version 8.0 is used by SQL Server Newer database server versions usually understand older protocol versions. When connecting to any version of SQL Server, you should not set this value to 5.0, because that version is a Sybase-specific protocol. When used with preparesql=3, setting this property to true causes the driver to cache column metadata for SELECT statements. Caching the metadata reduces the processing overhead when reusing statements that return small result sets having many columns, but may lead to unexpected errors if 37

38 Chapter 3 Database Prerequisites Property Description the database schema changes after the statement has been prepared. Use with care. charset Default: character set installed with the server domain instance appname Default: "jtds" progname Default: "jtds" wsid Default: client host name macaddress Default: " " Determines the byte value for character mapping for CHAR, VARCHAR, and TEXT values. The charset property applies to characters from the extended set (codes ). For NCHAR, NVARCHAR, and NTEXT values, it does not have any effect since these are stored using Unicode. Specifies the Windows domain in which to authenticate. If the domain property is present and the username and password are provided, jtds uses Windows (NTLM) authentication instead of the usual SQL Server authentication (i.e., the user and password provided are the domain user and password). This allows non-windows clients to log in to servers which are only configured to accept Windows authentication. If the domain property is present but no user name and password are provided, jtds uses its native Single-Sign-On library and logs in with the logged Windows user's credentials. It is necessary to be on Windows, be logged into a domain, and have the SSO library installed. For more information, refer to README.SSO in the distribution. Specifies the named instance to connect to. SQL Server can run multiple named instances (different server instances running on different TCP ports) on the same machine. When using Microsoft tools, you select a named instance by using host_name\instance_name instead of the usual host_name. With jtds, you must specify the instance name as a separate property. Specifies the application name. The value you specify is displayed by the Enterprise Manager or Profiler associated with the connection. Specifies the client library name. The value you specify is displayed by the Enterprise Manager or Profiler associated with the connection. Specifies the workstation ID. The value you specify is displayed by the Enterprise Manager or Profiler associated with the connection. Specifies the network interface card MAC address. It is displayed by the Enterprise Manager or Profiler associated with the connection and is needed to resolve issues regarding the number of clients allowed by the SQL Server license. The MAC address cannot be determined automatically from Java 38

39 Chapter 3 Database Prerequisites Property Description (i.e., without using native code) so you will have to specify it yourself if necessary. sendstringparametersasunicode Default: true lastupdatecount Default: true preparesql SQL Server default: 3 Determines whether string parameters are sent to the SQL Server database in Unicode or in the default character encoding of the database. There is a performance impact for the encoding logic, so set this option to false if unitext or univarchar data types are not in use or if charset is utf-8. If true, only the last update count is returned by executeupdate(). This property is useful if you are updating or inserting into tables that have triggers (such as replicated tables). There is no way to make the difference between an update count returned by a trigger and the actual update count, but the actual update count is always the last as the triggers execute first. If false, all update counts are returned; use getmoreresults() to loop through them. Specifies the mechanism used for Prepared Statements. Valid values are: 0 SQL is sent to the server each time without any preparation; literals are inserted in the SQL (slower). 1 Temporary stored procedures are created for each unique SQL statement and parameter combination (faster). 2 sp_executesql is used (fast). 3 sp_prepare and sp_cursorprep are used in conjunction with sp_execute and sp_cursorexecute (faster, SQL Server only). packetsize Defaults: 4096 for TDS 7.0/8.0; 512 for TDS 4.2/5.0 tcpnodelay Default: true lobbuffer Default: maxstatements Default: 500 Specifies the network packet size (a multiple of 512). Specify true to enable TCP_NODELAY on the socket; false to disable it. Specifies the amount of LOB data to buffer in memory before caching to disk. The value is in bytes for Blob data and chars for Clob data. Determines the number of statement prepares each connection should cache. A value of 0 disables statement caching. A value of Integer.MAX_VALUE ( ) enables fast 39

40 Chapter 3 Database Prerequisites Property Description caching (uses less memory and has no overhead associated with removing statements). The cache never release any cached statements, so although experience has shown that this is usually not a problem with most applications, use with care. logintimeout Default: 0 sockettimeout Default: 0 namedpipe Default: false xaemulation Default: true ssl Default: off Specifies the amount of time, in seconds, to wait for a successful connection before timing out. If namedpipe is true and logintimeout is non-zero, the value of logintimeout is used for the retry timeout when All pipe instances are busy error messages are received while attempting to connect to the server. If namedpipe is true and logintimeout is zero (the default), a value of 20 seconds is used for the named pipe retry timeout. Specifies the amount of time, in seconds, to wait for network activity before timing out. Use this property with caution. If a non-zero value is supplied, the value must be greater than the maximum time that the server takes to answer any query. Once the timeout value is exceeded, the network connection is closed. This property may be useful for detecting dead network connections in a pooled environment. When set to true, the named pipe communication is used instead of TCP/IP sockets to connect to the database. When the os.name system property starts with windows (case-insensitive), named pipes (both local and remote) are accessed through the Windows file system by opening a RandomAccessFile to the path. When SQL Server and the client are on the same machine, a named pipe usually has better performance than TCP/IP sockets because the network layer is eliminated. Otherwise, the JCIFS library is used. JCIFS provides a pure Java named pipe implementation and uses NTLM authentication, so the domain property is required. This feature supports the instance property (which changes the named pipe URL), but it does not currently support the named pipe at a location other than /sql/query on the server. The port property is ignored if set. When set to true, emulate XA distributed transaction support. When set to false, use experimental true distributed transaction support. For more information, see the README.XA file in the distribution. Specifies whether and how to use SSL for secure communication. 40

41 Chapter 3 Database Prerequisites Property Description off SSL is not requested or used. request SSL is requested; if the server does not support it, then a plain connection is used. require SSL is requested; if the server does not support it, then an exception is thrown. authenticate Same as require, except the server's certificate must be signed by a trusted CA. batchsize SQL Server default: 0 usecursors Default: false buffermaxmemory Default: 1024 bufferminpackets Default: 8 Specifies how many statements are sent to the server in a batch. The actual batch is broken up into pieces this large that are sent separately. Instructs jtds to use server-side cursors instead of direct selects (also called firehose cursors) for forward-only read-only result sets (with other types of result sets, serveror client-side cursors are always used). With server-side cursors, the SELECT query is sent and the server responds with all the resulting rows. This is the fastest approach but it means that the driver has to cache all results if another request needs to be made before all rows have been processed. When using multiple Statements per Connection, it is preferable to have server-side cursors instead: these allow the driver to request only a limited number of rows at a time (controllable through the fetchsize property of a statement). This means extra request-response cycles, but less caching by the driver. A so-called fast forward-only cursor is created when this property is set to true. Specifies the global buffer memory limit (in kilobytes) for all connections. When the amount of buffered server response packets reaches this limit, additional packets are buffered to disk. There is, however, one exception: each statement gets to buffer at least the number of packets specified by bufferminpackets to memory before this limit is enforced. This means that this limit can be and usually is exceeded. Server responses are buffered to disk only when a request is made on a statement while another statement belonging to the same connection still has not processed all of its results. These situations can be avoided in most cases by setting the usecursors property, but this also affects performance. Specifies the minimum number of packets per statement buffered to memory. 41

42 Chapter 3 Database Prerequisites Property Description To ensure good performance even when one statement caches a very large amount of data, each statement buffers at least this many packets before being forced to use a temporary file if the number of packets specified by buffermaxmemory is reached. Server responses are buffered to disk only when a request is made on a statement while another statement belonging to the same connection still has not processed all of its results. These situations can be avoided in most cases by setting the usecursors property, but this also affects performance. uselobs Default: true Controls whether, when using getobject(), large types (IMAGE, TEXT, NTEXT) should be mapped by default to LOB or Java types (string and byte[]). The default JDBC type constant returned is also controlled by the following properties when uselobs=true: Types.BLOB for IMAGE and Types.CLOB for TEXT/NTEXT. When uselobs=false, the JDBC type constant is controlled by Types.LONGVARBINARY for IMAGE and Types.LONGVARCHAR for TEXT/NTEXT. This property is useful when directly printing out the values returned by getobject() (e.g., when using JSTL or other frameworks): Blob and Clob do not implement tostring(), both because it is not required and because it can easily lead to OutOfMemoryError in unexpected situations, such as when logging data. The default setting of true has the advantage that the amount of data cached in memory for a large object can be controlled via the lobbuffer property. A setting of false still uses the Blob and Clob implementations internally; but the values are materialized to memory when getobject() is called, possibly leading to memory issues. Oracle Database Properties The Oracle JDBC Driver Supported Connection Properties table describes the connection properties that Oracle JDBC drivers support. Not all versions of Oracle support all properties. This table is the complete list for If you set a property and it is not supported by your version of Oracle, it is ignored. Table 10. Oracle JDBC Driver Supported Connection Properties Property user Data type: string password Description Specifies the username that Business Service Manager uses to connect to the database. Specifies the password for the Business Service Manager user. 42

43 Chapter 3 Database Prerequisites Property Description Data type: string database Data type: string server Data type: string internal_logon Data type: string defaultrowprefetch Data type: int defaultexecutebatch Data type: int processescapes Data type: boolean disabledefinecolumntype Data type: boolean DMSName Data type: string DMSType Data type: string AccumulateBatchResult Data type: boolean Default value: false oracle.jdbc.j2ee13compliant Data type: boolean Specifies the SID of the database. Specifies the hostname for the database. Specifies the username for performing an internal logon. The value is usually SYS or SYSDBA. Specifies the default number of rows to prefetch. Specifies the default batch size when using Oracle-style batching. If the value is false, then the default setting for Statement.setEscapeProccessing is false. This property is provided to avoid the need to remove calls from your code. When it has the value true, the method definecolumntype has no effect. The property is especially valuable if you use the same code with the Thin driver and with either the OCI or Server Internal driver. Setting the property to true is highly recommended when using the Thin driver, especially when the database character set contains four-byte characters that expand to two UCS2 surrogate characters, e.g., AL32UTF8. The method definecolumntype provides no benefit when used with the Thin driver. Specifies the name of the DMS Noun that is the parent of all JDBC DMS metrics. Specifies the type of the DMS Noun that is the parent of all JDBC DMS metrics. When using Oracle-style batching, JDBC determines when to flush a batch to the database. If this property is true, the number of modified rows accumulated across all batches is flushed from a single statement. The default is to count each batch separately. If the value of this property is true, JDBC uses strict compliance for some edge cases. 43

44 Chapter 3 Database Prerequisites Property Description In general, Oracle's JDBC drivers allow some operations that are not permitted in the strict interpretation of J2EE 1.3. Setting this property to true causes those cases to throw a SQLException. There are some other edge cases where Oracle's JDBC drivers have slightly different behavior than defined in J2EE 1.3. This results from Oracle having defined the behavior prior to the J2EE 1.3 specification and the resultant need for compatibility with existing customer code. Setting this property results in full J2EE 1.3 compliance at the cost of incompatibility with some customer code. This can be either a system property or a connection property. The default value of this property is false in classes12.jar and ojdbc12.jar. The default value is true in classes12dms.jar and ojdbc14dms.jar. It is true by default in *dms.jar files because they are used almost exclusively in Oracle Application Server and so J2EE compatibility is more important than compatibility with previous Oracle versions. oracle.jdbc.tcpnodelay Data type: boolean defaultnchar Data type: boolean usefetchsizewithlongcolumn Data type: boolean remarksreporting Data type: boolean includesynonyms Data type: boolean restrictgettables Data type: boolean If the value of this property is true, the TCP_NODELAY property is set on the socket when using the Thin driver. See java.net.socketoptions.tcp_nodelay. This can be either a system property or a connection property. If the value of this property is true, the default mode for all character data columns is NCHAR. If the value of this property is true, then JDBC prefetches rows even if there is a LONG or LONG RAW column in the result. By default, JDBC fetches only one row at a time if there are LONG or LONG RAW columns in the result. Setting this property to true can improve performance but can also cause a SQLException if the results are too big. If the value of this property is true, OracleDatabaseMetaData includes remarks in the metadata. This can result in a substantial reduction in performance. If the value of this property is true, JDBC includes synonyms when getting information about a column. If the value of this property is true, JDBC returns only accessible tables for DatabaseMetaData.getTables. By default, JDBC returns things that are not accessible tables. These can be non-table objects or accessible synonyms for inaccessible tables. If this property is true, JDBC returns only accessible tables. This has a substantial performance penalty. 44

45 Chapter 3 Database Prerequisites Property fixedstring Data type: boolean oracle.jdbc.ocinativelibrary Data type: string SetBigStringTryClob Data type: boolean Description If the value of this property is true, JDBC uses the FIXED CHAR semantic when setobject is called with a String argument. By default, JDBC uses VARCHAR semantics. The difference is in blank padding. With the default, there is no blank padding so, for example, 'a' does not equal 'a ' in a CHAR(4). If true, these two are equal. Specifies the name of the native library for the OCI driver. If not set, the default name libocijdbcx (where X is a version number) is used. Setting this property to true forces the PreparedStatement.setString() method to use setstringforclob() if the data is larger than 32,765 bytes. Using this method with VARCHAR and LONG columns may cause large data to be truncated silently, or cause other errors differing from the normal behavior of setstring(). IBM DB2 Database Properties The IBM DB2 Universal JDBC Driver Supported Connection Properties table describes the connection properties that DB2 JDBC drivers support. Table 11. IBM DB2 Universal JDBC Driver Supported Connection Properties Property activeserverlistjndiname Data type: string clientaccountinginformation Data type: string clientapplicationinformation Data type: string Description Identifies a JNDI reference to a DB2ActiveServerList instance in a JNDI repository of alternate server information. If the value of activeserverlistjndiname is not null, connections can failover to an alternate server that is specified in the DB2ActiveServerList instance referenced by the value. If activeserverlistjndiname is null, connections do not failover using alternate server information from a JNDI repository. Specifies accounting information for the current client for the connection. This information is for client accounting purposes. The value can change during a connection. For DB2 servers for Linux, UNIX, and Windows, the maximum length is 255 bytes. A Java empty string ("") is valid for this value, but a Java null value is not valid. Specifies application information for the current client for the connection. This information is for client accounting purposes. The value can change during a connection. 45

46 Chapter 3 Database Prerequisites Property Description For DB2 servers for Linux, UNIX, and Windows, the maximum length is 255 bytes. A Java empty string ("") is valid for this value, but a Java null value is not valid. clientuser Data type: string clientworkstation Data type: string clischema Data type: string currentfunctionpath Data type: string currentlocktimeout Data type: int currentpackagepath Data type: string currentpackageset Data type: string Default value: nullid Specifies the current client username for the connection. This information is for client accounting purposes. Unlike the JDBC connection username, the value can change during a connection. For DB2 servers for Linux, UNIX, or Windows, the maximum length is 255 bytes. Specifies the workstation name for the current client for the connection. This information is for client accounting purposes. The value can change during a connection. For DB2 servers for Linux, UNIX, or Windows, the maximum length is 255 bytes. A Java empty string ("") is valid for this value, but a Java null value is not valid. Specifies the schema of the DB2 shadow catalog tables or views that are searched when an application invokes a DatabaseMetaData method. Specifies the SQL path that is used to resolve unqualified data type names and function names in SQL statements that are in JDBC programs. The value is a comma-separated list of schema names. Those names can be ordinary or delimited identifiers. For DB2 servers for Linux, UNIX, or Windows, the maximum length is 254 bytes. Directs DB2 for Linux, UNIX, and Windows servers to wait for a lock when the lock cannot be obtained immediately. A value of 0 (zero) means no wait. A value of -1 means to wait indefinitely. A positive integer indicates the number of seconds to wait for a lock. Defines a comma-separated list of collections on the server. The DB2 server searches these collections for the DB2 packages for the DB2 Universal JDBC Driver. The precedence rules for the currentpackagepath and currentpackageset properties follow the precedence rules for the DB2 CURRENT PACKAGESET and CURRENT PACKAGE PATH special registers. Specifies the collection ID to search for DB2 packages for the DB2 Universal JDBC Driver. If currentpackageset is set, its value overrides the value of jdbccollection. 46

47 Chapter 3 Database Prerequisites Property Description Multiple instances of the DB2 Universal JDBC Driver can be installed at a database server by running the DB2binder utility multiple times. The DB2binder utility includes a -collection option that lets the installer specify the collection ID for each DB2 Universal JDBC Driver instance. To choose an instance of the DB2 Universal JDBC Driver for a connection, specify a currentpackageset value that matches the collection ID for one of the DB2 Universal JDBC Driver instances. The precedence rules for the currentpackagepath and currentpackageset properties follow the precedence rules for the DB2 CURRENT PACKAGESET and CURRENT PACKAGE PATH special registers. currentschema Data type: string Specifies the default schema name that is used to qualify unqualified database objects in dynamically prepared SQL statements. This property sets the value in the CURRENT SCHEMA special register on a server other than z/os. Do not set this property for a z/os server. currentsqlid Specifies: Data type: string The authorization ID that is used for authorization checking on dynamically prepared CREATE, GRANT, and REVOKE SQL statements. The owner of a table space, database, storage group, or synonym that is created by a dynamically issued CREATE statement. The implicit qualifier of all table, view, alias, and index names specified in dynamic SQL statements. This property sets the value in the CURRENT SQLID special register on a z/os server. If it is not set, the default schema name is the value in the CURRENT SQLID special register. cursorsensitivity Data type: string Default: TYPE_SCROLL_SENSITIVE_STATIC databasename Data type: string Specifies whether the java.sql.resultset.type_scroll_sensitive value for a JDBC ResultSet maps to the SENSITIVE DYNAMIC attribute or the SENSITIVE STATIC attribute for the underlying DB2 cursor. Possible values are TYPE_SCROLL_SENSITIVE_STATIC (default) and TYPE_SCROLL_SENSITIVE_DYNAMIC. The property is ignored for database servers that do not support sensitive dynamic scrollable cursors. Provides the name of the database server. This name is used as the database portion of the connection URL. The name depends 47

48 Chapter 3 Database Prerequisites Property Description on whether Universal Type 4 Connectivity or Universal Type 2 Connectivity is used. For Universal Type 4 Connectivity: If the connection is to z/os server, the databasename value is the DB2 location name defined during installation. All characters in this value must be uppercase characters. You can determine the location name by executing the following SQL statement on the server: SELECT CURRENT SERVER FROM SYSIBM.SYSDUMMY1; If the connection is to a DB2 server for Linux, UNIX, or Windows, the databasename value is the database name defined during installation. If the connection is to an IBM Cloudscape server, the databasename value is the fully-qualified name of the file that contains the database. This name must be enclosed in double quotation marks (" "). For example: "c:/databases/testdb" If this property is not set, connections are made to the local site. For Universal Type 2 Connectivity: The databasename value is the database name defined during installation, if the value of the servername connection property is null. If the value of servername is not null, the databasename value is a database alias. deferprepares Data type: boolean Default value: true description Data type: string drivertype Data type: int Default value: 2 fullymaterializelobdata Data type: boolean Default value: true Specifies whether to defer prepare operations until run time. Deferring prepare operations can reduce network delays. However, if you defer prepare operations, you need to ensure that input data types match DB2 table column types. The default is true for Universal Type 4 Connectivity. The property does not apply to Universal Type 2 Connectivity. Provides a description of the data source. For the DataSource interface, determines which driver to use for connections. Valid values are 2 (default) or 4. Indicates whether the driver retrieves LOB locators for FETCH operations. If the value is true, LOB data is fully materialized within the JDBC driver when a row is fetched. If this value is false, LOB 48

49 Chapter 3 Database Prerequisites Property Description data is streamed. The driver uses locators internally to retrieve LOB data in chunks on an as-needed basis. It is highly recommended that you set this value to false when you retrieve LOBs that contain large amounts of data. This property has no effect on stored procedure parameters or LOBs that are fetched using scrollable cursors. LOB stored procedure parameters are always fully materialized. LOB locators are always used for data that is fetched using scrollable cursors. gsscredential Default value: org.ietf.jgss.gsscredential jdbccollection Data type: string Default value: NULLID kerberosserverprincipal Data type: string logintimeout Data type: int Default value: 0 For a data source that uses Kerberos security, specifies a delegated credential that is passed from another principal. 1 Delegated credentials are used in multi-tier environments, such as when a client connects to WebSphere Application Server, which, in turn, connects to DB2. You obtain a value for this property from the client by invoking the GSSContext.getDelegCred() method. This method is part of the IBM Java Generic Security Service (GSS) API. If you set this property, you also must set the Mechanism and KerberosServerPrincipal properties. This property applies only to Universal Type 4 Connectivity. Specifies the collection ID for the packages that are used by an instance of the DB2 Universal JDBC Driver at run time. This property is used with the DB2Binder -collection option. The DB2Binder utility must have previously bound DB2 Universal JDBC Driver packages at the server using a -collection value that matches the jdbccollection value. The jdbccollection setting does not determine the collection that is used for SQLJ applications, For SQLJ, the collection is determined by the -collection option of the SQLJ customizer. The jdbccollection property does not apply to Universal Type 2 connectivity on DB2 for z/os. For a data source that uses Kerberos security, specifies the name that is used for the data source when it is registered with the Kerberos Key Distribution Center (KDC). This property applies only to Universal Type 4 Connectivity. Specifies the maximum time, in seconds, to wait for a connection to a data source or for SQL requests to that data source. After the number of seconds specified by logintimeout have elapsed, the driver closes the connection to the data source. 1 For more information on using Kerberos security with the DB2 Universal JDBC Driver, refer to Kerberos security under the DB2 Universal JDBC Driver in the IBM Web site, 49

50 Chapter 3 Database Prerequisites Property Description This property is not supported for Universal Type 2 connectivity on DB2 in the z/os or OS/390 environment. logwriter Data type: java.io.printerwriter Default value: null password Data type: string portnumber Data type: int readonly Data type: boolean Default value: false resultsetholdability Data type: int retrievemessagesfromserverongetmessage Data type: boolean Default value: false securitymechanism Data type: string Specifies the character output stream to which all logging and trace messages for the DataSource object are printed. The default value of null specifies no logging or tracing for the DataSource is output. Specifies the password to use for establishing connections. When you use the DataSource interface to establish a connection, you can override this property by invoking this form of the DataSource.getConnection method: getconnection(user, password); Specifies the number of the port where the DRDA server is listening for requests. Specifies whether the connection is read-only. Specifies whether cursors remain open after a commit operation. Valid values are com.ibm.db2.jcc.db2basedatasource.hold_cursors_over_commit or com.ibm.db2.jcc.db2basedatasource.close_cursors_at_commit. These values are the same as the ResultSet.HOLD_CURSORS_OVER_COMMIT and ResultSet.CLOSE_CURSORS_AT_COMMIT constants that are defined in JDBC 3.0. Specifies whether JDBC SQLException.getMessage calls cause the DB2 Universal JDBC Driver to invoke a DB2 for OS/390 or z/os stored procedure that retrieves the message text for the error. The default value, false, specifies that the full message text is not returned to the client. An alternative to setting this property to true is to use the DB2-only DB2Sqlca.getMessage method in applications. Both techniques result in a stored procedure call, which starts a unit of work. Specifies the DRDA security mechanism. Possible values are: CLEAR_TEXT_PASSWORD_SECURITY User ID and password USER_ONLY_SECURITY User ID only 50

51 Chapter 3 Database Prerequisites Property Description ENCRYPTED_PASSWORD_SECURITY User ID, encrypted password ENCRYPTED_USER_AND_PASSWORD_SECURITY Encrypted user ID and password KERBEROS_SECURITY Kerberos If this property is provided, the specified security mechanism is the only mechanism that is used. If the security mechanism is not supported by the connection, an exception is thrown. If no value is specified for this property, the requester attempts to connect using the most secure mechanism possible. If a connection cannot be established because the server does not support that security mechanism, the server returns a list of alternate choices to the requester. The requester tries each of those security mechanisms until a connection can be established with one of them. If there are no alternative choices, or if all alternative choices fail, an exception is thrown. servername Data type: string tracefile Data type: string tracefileappend Data type: boolean Default value: false tracelevel Data type: int Specifies the host name or the TCP/IP address of the data source. Specifies the name of a file into which the DB2 Universal JDBC Driver writes trace information. The tracefile property is an alternative to the logwriter property for directing the output trace stream to a file. Specifies whether to append to or overwrite the file that is specified by the tracefile property. The default value, false, means the file that is specified by the tracefile property is overwritten. Specifies what to trace. You can specify one or more of the following traces with the tracelevel property: com.ibm.db2.jcc.db2basedatasource.trace_none com.ibm.db2.jcc.db2basedatasource.trace_connection_calls com.ibm.db2.jcc.db2basedatasource.trace_statement_calls com.ibm.db2.jcc.db2basedatasource.trace_result_set_calls com.ibm.db2.jcc.db2basedatasource.trace_driver_configuration com.ibm.db2.jcc.db2basedatasource.trace_connects com.ibm.db2.jcc.db2basedatasource.trace_drda_flows com.ibm.db2.jcc.db2basedatasource.trace_result_set_meta_data com.ibm.db2.jcc.db2basedatasource.trace_parameter_meta_data com.ibm.db2.jcc.db2basedatasource.trace_diagnostics 51

52 Chapter 3 Database Prerequisites Property Description com.ibm.db2.jcc.db2basedatasource.trace_sqlj com.ibm.db2.jcc.db2basedatasource.trace_xa_calls (Universal Type 2 connectivity for DB2 for Linux, UNIX and Windows only) com.ibm.db2.jcc.db2basedatasource.trace_all To specify more than one trace, use one of these techniques: Use bitwise OR ( ) operators with two or more trace values. For example, to trace DRDA flows and connection calls, specify this value for tracelevel: TRACE_DRDA_FLOWS TRACE_CONNECTION_CALLS Use a bitwise complement (~) operator with a trace value to specify all except a certain trace. For example, to trace everything except DRDA flows, specify this value for tracelevel: ~TRACE_DRDA_FLOWS user Data type: string Specifies the user ID to use for establishing connections. When you use the DataSource interface to establish a connection, you can override this property value by invoking this form of the DataSource.getConnection method: getconnection(user, password); Verifying the Database Verify the database after installing and configuring it, and after installing Business Service Manager. After installing and configuring the database, check that the data repository has been correctly configured and is accessible from Business Service Manager. 1. Verify the database while installing Business Service Manager. During the installation process, you must enter the database server connection and login information. You have the opportunity to test this connection and make any necessary corrections. 2. Check that the required database tables have been created when Business Service Manager starts. The EventDatabaseListener.xml configuration file located in the BSM_HOME/vsm/config directory contains the table definitions. Check that the table EM_Events_TBL has been created. 52

53 CHAPTER 4 Installation Prerequisites The Installation Prerequisites chapter describes information that must be provided and tasks that must be performed before installing Business Service Manager components. You must configure databases for Business Service Manager before installing. For more information, see Database Prerequisites [p. 25]. If you are doing a new installation of Business Service Manager, and you have other Gomez products installed, upgrade those products to Release 11.7 ( for Vantage for Java and.net Monitoring) before installing Business Service Manager. For more information, see Compatible Gomez Solution Releases with Business Service Manager 11.7 [p. 17]. For new installations of all Gomez products, install any of the products before installing Business Service Manager. User Account License Business Service Manager can be installed under any user account. If you are installing on a Windows platform, your user account must be part of the Admin group. During the installation, you are prompted for the installation directory name. If a permanent license is not already installed before you install Business Service Manager, a temporary (evaluation) license is installed automatically. NOTE A new permanent license is required for existing Business Service Manager users who are migrating from an earlier release. For more information, contact Compuware Customer Support. When you receive a permanent license, use the Distributed License Management (DLM) application to install the license. DLM is installed automatically during the Business Service Manager installation. For more information, refer to the Distributed License Management Installation Guide. 53

54 Chapter 4 Installation Prerequisites Port Settings Make sure that all port settings are correct and do not conflict with other products. Firewall Settings If any components of your Business Service Manager system will be installed on different sides of a firewall, you must verify that the correct port settings have been made on the firewall. A number of TCP connections are used by the Service Model server, the Configuration Client, the application server, and the database. All communication between these components are carried out over TCP to ensure reliable transport. The following table identifies default ports used by Gomez. NOTE If your system configuration does not use the default ports, you will need to know the assigned ports to configure Gomez during installation. Table 12. Default Connection Ports Connection Gomez Service Model 11.7 service application server Oracle IBM DB2 Microsoft SQL Server JMX remote port Compuware Open Server service wrapper port OSGI service HTTP OSGI console Default Port , (JCC) or 6789 (net) If you cannot use the default port settings, you can change the port by running the Setup program during installation, or go to BSM_HOME/bin/Setup.exe to change ports after an initial installation. Consider the following factors when configuring a firewall for Gomez. Configuration Client The Configuration Client opens one TCP session from a random high port (higher than 1023) to JSDT (5005). The firewall needs to allow SYN packets from the client to the 54

55 Chapter 4 Installation Prerequisites server, as well as non-syn packets in both directions. The Service Navigator requires the JSDT port to be open. The Configuration Client opens a TCP session to port 8080 (Web server) on the Web server. This connection requires SYN packets from the client to the Web server, as well as non-syn packets in both directions. If the Configuration Client is used to query the database, it requires a port opened to the database server. The default port used by each supported database is listed in the table above. Service Model server The Service Model server requires a TCP connection to a database to operate. The server initiates all such connections from a random port (higher than 1023). The default ports used by the supported databases are listed in the table above. Service Model server in fault-tolerant setup When the Service Model server is used in a fault-tolerant setup, a heartbeat is sent across the network via the JSDT (5005) port. The connection is initiated from the backup server, and the firewall must allow TCP connections to be opened from the backup server to the primary server. The primary server does not initiate a connection to the backup server at any time. The firewall must also be configured to allow all servers to connect to the database. Web server The Web server requires TCP connections to both the Service Model server and the database. Connections to the server are initiated by the Web server from a random high port to the JSDT (5005) port. Similarly, connections to the database are also initiated from a random high port to the appropriate database port, as given in the above table. Web clients should also be able to access the Web server, so the Web server port 8080 should also be opened to clients who will access the server via the Web interface. Modem Settings Any modem installed to handle Business Service Manager message services, such as those involved in alarms (e.g., SMS), must be dedicated entirely to these services and not configured for any other purpose. Any attempt to otherwise configure the messaging modem results in errors, with messages indicating the port concerned is busy. Before installing Business Service Manager, make sure the ports you intend to use for alarm services are clear for exclusive use. Configuration and Log Files In general, configuration and log files for the client are located in BSM_HOME/config; configuration and log files for the server are located in BSM_HOME/VSM/config. Some files are available in both these locations as well as in WEBROOT/WEB-INF/config, where WEBROOT is the application server installation. If you need to edit a configuration file, use the location specified in the relevant procedure in this document. 55

56 Chapter 4 Installation Prerequisites CAUTION It is recommended that you contact Compuware Customer Support for assistance before you attempt to modify Service Model system files. File Locations The following files are used for logging configuration and output: Configuration Client Configuration BSM_HOME/config/logging/client_log4j.xml Output BSM_HOME/tmp/Client.log Service Model server Configuration BSM_HOME/vsm/config/logging/server_log4j.xml Output BSM_HOME/vsm/tmp/CS.log Dashboards Configuration WEBROOT/WEB-INF/config/logging/web_log4j.xml. Output If you are using the default Tomcat Web server, the output is logged to BSM_HOME/tomcat/logs/tomcat.log. Properties file WEBROOT/WEB-INF/classes/log4j.properties. Adjusting Log Output The log configuration (log4j) files are XML. The root element in the configuration file is the main logger. <root> <level value="warn"/> <appender-ref ref="clientdotlog"/> </root> To specify the level of logging output, you must manually edit the log file. The level attribute defines the level of output that will be logged. The following values are valid. DEBUG Provide verbose information for developers and support staff. INFO Log all ordinary activity for the system administrator. WARN Log only indications that something might go wrong. ERROR Log only exceptions or errors. FATAL Log only severe problems that terminate the program. Each level includes the lower-level messages. For example, if the level is set to WARN, the log will include output for WARN, ERROR, and FATAL. 56

57 Chapter 4 Installation Prerequisites The appender-ref attribute references a defined appender to which log messages are directed. In the Service Model, the appender is defined as in the following example, which specifies a File named Client.log in the tmp directory. <appender name="clientdotlog" class="org.apache.log4j.rollingfileappender"> <param name="maxfilesize" value="10mb"/> <param name="file" value="../tmp/client.log"/> <param name="maxbackupindex" value="10"/> <layout class="org.apache.log4j.patternlayout"> <param name="conversionpattern" value="%d{iso8601} %c{1}-%p: %m%n"/> </layout> </appender> A Log4j configuration file may have only a root logger, or it may include additional logger elements, as in the following example. <logger additivity="false" name="com.proxima.centauri.util.clock.systemclock"> <level value="warn"/> <appender-ref ref="service_model_hdi"/> </logger> The name attribute in a logger is usually a fully qualified package name. All log messages generated from this package will be logged to this logger. System Clock Settings A maintenance system is recommended to keep the clock settings within normal operating bounds. As a system designed to handle both real-time events and historical events, Gomez depends on reasonable accuracy in system clock settings, including settings on remote machines providing event data to it. Check that system clocks are reasonably accurate and synchronized before you launch your system. Saving data checkpoints within Gomez is intended to assist in data recovery in situations where the system comes down or is stopped. Setting a system clock back before restart is not recommended or supported. CAUTION Input of events with times out of phase with the Gomez system time can have unexpected and anomalous results, particularly in Out of Order data operations. Disk Space Issues During installation, you may be advised that insufficient disk space is available for extraction of files used in the installation. Such a message indicates that the default temporary area is too small. If insufficient space is available for installation, you are prompted to specify a directory with adequate space. For UNIX or Linux, an alternative is to set the IATEMPDIR variable before commencing installation to the path for an area known to have enough disk space, but you will 57

58 Chapter 4 Installation Prerequisites still need space in tmp for the Eclipse install manager. In Windows, set the TMP environment variable to a suitable path. 58

59 CHAPTER 5 New Installations Business Service Manager (BSM) can be installed on a variety of operating systems, with components distributed across multiple servers, to meet different user scenarios. The installation procedures are the same whether you are deploying BSM on physical or supported virtual server environments. BSM has Windows, UNIX and Linux installers designed to help meet those varied installation requirements. On the Gomez installation browser, the Windows installer is located on the Components/Upgrades tab. The Installation and Configuration Process There are several options for how to install and configure BSM, but the basic process is virtually the same in all cases. 1. Create BSM database(s) before installing. For more information, see Database Prerequisites [p. 25]. 2. During installation, connect to the database and configure port settings. 3. Configure the application server. By default, Apache Tomcat is the installed application server, without SSL features. Optionally, you can generate an SSL key and associated certificate for Tomcat to protect communications. You also can use supported releases of WebLogic or WebSphere application servers. For more information, see Configuring the Application Server [p. 76]. 4. Configure some adaptors to important data sources to ensure connectivity to data. For more information, see Data Collection for Business Service Management in the Business Service Manager Data Collection User Guide. 5. Start building your Service Model. Refer to the Business Service Manager Service Model User Guide. 6. Install a permanent license file for BSM. 59

60 Chapter 5 New Installations Installing Components on Separate Servers It is possible and frequently recommended for performance considerations to install BSM components on separate servers. The installation program provides options to install the Service Model server, Web application server and components, and Connection Manager server individually so they can be installed on separate machines. In addition, you can install a database on a remote machine and connect to it during the installation process. When you install BSM components on separate machines, ensure that the installation meets the following requirements: Each machine must comply with the system requirements for installing BSM. For more information, see System Requirements [p. 17]. The components must be configured with the correct connection information and port settings to communicate across machines and avoid port conflicts. For more information, see Port Settings [p. 54] and Configuring the Application Server [p. 76]. The database connection and login information must be configured for the remote connection, and the necessary permissions must be granted. For more information, see Configuring the Database [p. 26]. For more information, see Business Service Manager Deployment Considerations [p. 18]. Installing Multiple Business Service Manager Instances on the Same Machine You can install multiple BSM instances on the same machine to create, for example, staging and production systems, or for upgrades from a previous release. For more information, see Upgrading and Migrating Business Service Manager to Release 11.7 [p. 93]. There are important configuration and setup options that must be enabled to install multiple instances on one machine. For more information, see Usage Scenarios for Multiple Service Model Servers in the Business Service Manager Administration Guide. Windows Standard Installation The Standard installation includes the following components: Service Model server Apache Tomcat Web server Web application Configuration Client 1. Connect to your installation host with the user name that owns the installation. 2. Insert DVD 1 and run setup.exe. 60

61 Chapter 5 New Installations 3. In the Gomez Setup window, go to the Components/Upgrades tab and click Business Service Manager to open the installation wizard. Select the 32- or 64-bit version according to your server specifications. A window displays the progress for extracting the installer. Preparing to install may take several minutes. 4. Accept the license agreement and click Next. 5. Choose an installation folder. By default, C:\Program Files\Compuware\Business Service Manager is selected. Click Choose to designate another folder. NOTE You may be prompted to specify a temporary directory. For more information, see Disk Space Issues [p. 57]. 6. Accept the default installation type. In the Choose Install Set screen, Standard Installation is selected by default. Click Next. 7. In the Pre-Installation Summary screen, review your selections, then click Install. Installation may take several minutes. 8. When the Setup Wizard appears, use the first screen to define your database(s). You can create separate databases for the server component and the dashboard. The Database screen varies depending on the database you select. The options are described below. NOTE For all database types, if you created separate databases for the Server and Dashboard, the database host, port, user and password must be the same for both. The following figure displays the options for Microsoft SQL Server. 61

62 Chapter 5 New Installations Database Type The Database Type list includes the supported database types. Select the type for the database you created before beginning installation. For more information, see Database Prerequisites [p. 25]. Host Name Specify the database host machine. NOTE If you select Oracle Grid as the database type, this option does not appear. Port Number The default port, which varies depending on the database, is entered automatically. Change the port number if you are not using the default. NOTE If you select Oracle Grid as the database type, this option does not appear. Server and Dashboard Database(s) Specify the database (or instance) name for each. If you want to use only one database, enter the same database name for both Server and Dashboard. 62

63 Chapter 5 New Installations NOTE The Instance field appears if you selected Oracle as the database type. For all other database types, the Database field appears. MSSQL only: The Use Default Database option appears next to the Database field, and is selected by default. If you are not using the default database, clear the Use Default Database check box and type the database name in the Database field. Server and Dashboard Tablespace NOTE If you selected MSSQL as the database type, this field does not appear. By default, Use Default Tablespace is selected. If you do not want to use the default, clear the check box and type the tablespace name in the field. Trusted Connection MSSQL only: To enable a trusted connection for a remote database, select this option and provide the logon information for the account under which the Service Model server (service) and Vantage Dashboards service (the Tomcat service) must run for the trusted connection to be allowed. Note that, in the account setup, this account must be granted the right logon as service. Trusted Account Enter the account name in the form domain\username. Trusted Password Enter the password for the account. If you select this option, the Database Authentication options are not available. Database Authentication Select this option if your database is not Microsoft SQL Server or you are not using a Trusted Connection. Enter the login information: User Name Provide the user name for logging on to the specified database. If you selected Oracle, Oracle grid, or DB2 as the database type, the default user name is provided automatically. Password Provide the password for the specified user name. Load Balance This option appears only if you selected Oracle grid as the database type. If the Oracle grid spans several hosts, click Add as needed to create a row for entering each Host name and Port. Selection a case-sensitive collation MSSQL: From the list, select the collation for your SQL Server database. The collation specifies the rules for sorting and comparing strings of character data, based on particular languages and locales. For assistance, consult with your database administrator. 9. Click Check Connection. 63

64 Chapter 5 New Installations Make sure the connection information is correct and a connection is established. 10. Click Next to display the Configuration options. The default port is automatically displayed for each platform or service: 11. Change the port numbers as needed. Click the Verify Ports button to test your port configurations. If a port is in conflict a red X will appear next to the port. NOTE If you are installing more than one Business Service Manager instance on the same machine, you must increment the port numbers after the first instance, to avoid conflicts. 12. Click Next to display the Auto-Start options. Options to start the Configuration Client and display the web interface when installation is completed are provided. Select or clear the options as desired. 13. Click Done. The Setup Wizard closes and installation continues. A popup window displays the progress of services being installed and started. Installation may take several minutes. 14. When installation is completed, click Close to close the progress window. 15. Click Done to close the installation wizard 64

65 Chapter 5 New Installations 16. Close the Gomez Setup window. You are now ready to configure the application server. For more information, see Configuring the Application Server [p. 76]. Client Installation Use the Client installation option to install only the Configuration Client, for example on a separate machine from the Service Model server. 1. Connect to your installation host with the user name that owns the installation. 2. Insert DVD 1 and run setup.exe. 3. In the Gomez Setup window, go to the Components/Upgrades tab and click Business Service Manager to open the installation wizard. Select the 32- or 64-bit version according to your server specifications. A window displays the progress for extracting the installer. Preparing to install may take several minutes. 4. Accept the license agreement and click Next. 5. Choose an installation folder. By default, C:\Program Files\Compuware\Business Service Manager is selected. Click Choose to designate another folder. NOTE You may be prompted to specify a temporary directory. For more information, see Disk Space Issues [p. 57]. 6. In the Choose Install Set screen, select Client Installation. 7. In the Pre-Installation Summary screen, review your selections, then click Install. A popup window displays the progress of installation. 8. When installation is completed, click Close to close the progress window. 9. Click Done to close the installation wizard 10. Close the Gomez Setup window. Custom Installation The Custom installation option enables you to select which components to install. For example, you may want to install the Dashboard components on a separate machine. In this scenario, you should have already installed a Service Model server on another machine. During the Dashboard-only install, you will need to identify the Service Model server host so the two servers can communicate. You also will need to have a database created and accessible. By default, the Custom installation option has the Standard components selected. You cannot perform a custom installation from the command line. Although you can specify CUSTOM as the installation type, you cannot select which components to install or exclude from installation. 65

66 Chapter 5 New Installations 1. Connect to your installation host with the user name that owns the installation. 2. Insert DVD 1 and run setup.exe. 3. In the Gomez Setup window, go to the Components/Upgrades tab and click Business Service Manager to open the installation wizard. Select the 32- or 64-bit version according to your server specifications. A window displays the progress for extracting the installer. Preparing to install may take several minutes. 4. Accept the license agreement and click Next. 5. Choose an installation folder. By default, C:\Program Files\Compuware\Business Service Manager is selected. Click Choose to designate another folder. NOTE You may be prompted to specify a temporary directory. For more information, see Disk Space Issues [p. 57]. 6. Make the selections for custom installation. In the first Choose Install Set screen, select Custom, then click Next. In the second screen, all the Standard components are selected by default. Clear or select components as needed. 7. In the Pre-Installation Summary screen, review your selections, then click Install. Installation may take several minutes. 8. When the Setup Wizard appears, use the first screen to define your database(s). You can create separate databases for the server component and the dashboard. The Database screen varies depending on the database you select. The options are described below. NOTE For all database types, if you created separate databases for the Server and Dashboard, the database host, port, user and password must be the same for both. The following figure displays the options for Microsoft SQL Server. 66

67 Chapter 5 New Installations Database Type The Database Type list includes the supported database types. Select the type for the database you created before beginning installation. For more information, see Database Prerequisites [p. 25]. Host Name Specify the database host machine. NOTE If you select Oracle Grid as the database type, this option does not appear. Port Number The default port, which varies depending on the database, is entered automatically. Change the port number if you are not using the default. NOTE If you select Oracle Grid as the database type, this option does not appear. Server and Dashboard Database(s) Specify the database (or instance) name for each. If you want to use only one database, enter the same database name for both Server and Dashboard. 67

68 Chapter 5 New Installations NOTE The Instance field appears if you selected Oracle as the database type. For all other database types, the Database field appears. MSSQL only: The Use Default Database option appears next to the Database field, and is selected by default. If you are not using the default database, clear the Use Default Database check box and type the database name in the Database field. Server and Dashboard Tablespace NOTE If you selected MSSQL as the database type, this field does not appear. By default, Use Default Tablespace is selected. If you do not want to use the default, clear the check box and type the tablespace name in the field. Trusted Connection MSSQL only: To enable a trusted connection for a remote database, select this option and provide the logon information for the account under which the Service Model server (service) and Vantage Dashboards service (the Tomcat service) must run for the trusted connection to be allowed. Note that, in the account setup, this account must be granted the right logon as service. Trusted Account Enter the account name in the form domain\username. Trusted Password Enter the password for the account. If you select this option, the Database Authentication options are not available. Database Authentication Select this option if your database is not Microsoft SQL Server or you are not using a Trusted Connection. Enter the login information: User Name Provide the user name for logging on to the specified database. If you selected Oracle, Oracle grid, or DB2 as the database type, the default user name is provided automatically. Password Provide the password for the specified user name. Load Balance This option appears only if you selected Oracle grid as the database type. If the Oracle grid spans several hosts, click Add as needed to create a row for entering each Host name and Port. Selection a case-sensitive collation MSSQL: From the list, select the collation for your SQL Server database. The collation specifies the rules for sorting and comparing strings of character data, based on particular languages and locales. For assistance, consult with your database administrator. 9. Click Check Connection. 68

69 Chapter 5 New Installations Make sure the connection information is correct and a connection is established. 10. Click Next to display the Configuration options. The default port is automatically displayed for each platform or service: 11. Change the port numbers as needed. Click the Verify Ports button to test your port configurations. If a port is in conflict a red X will appear next to the port. NOTE If you are installing more than one Business Service Manager instance on the same machine, you must increment the port numbers after the first instance, to avoid conflicts. 12. Click Next to display the Auto-Start options. Options to start the Configuration Client and display the web interface when installation is completed are provided. Select or clear the options as desired. 13. Click Done. The Setup Wizard closes and installation continues. A popup window displays the progress of services being installed and started. Installation may take several minutes. 14. When installation is completed, click Close to close the progress window. 15. Click Done to close the installation wizard 69

70 Chapter 5 New Installations 16. Close the Gomez Setup window. Windows Command-Line Installation In Windows, BSM can be installed from the command line, invoking a file that include configuration properties and commands for various administrative tasks before and after installation. NOTE From the command line, you can only install predefined sets of components. The only way to install a component after an initial installation that excluded it is to use the Custom option in the GUI-based installer. The preferred method for installing from the command line is to execute the command install -f propertiesfile where propertiesfile is the full absolute path to a suitably formatted properties file in a directory other than the directory containing the executable installation file. For more information, see Properties File for Command-Line Installation [p. 72]. An alternative is to create a file named installer.properties or install.properties in the directory containing the executable installation file, or copy the file into the directory. This file must contain the following lines: INSTALLER_UI=silent SETUP_PROPERTIES_FILE=propertiesfile In the second line, propertiesfile is the full pathname of the file containing the configuration values for installation, such as the installation type, the target directory, and the database configuration. When the properties file is present in the same directory as the executable installation file, the bare command install initiates batch-mode installation. The installer checks its resident directory for the required properties file (first installer.properties, then install.properties if the former file is not present) to obtain configuration values for the installation. Installing on UNIX You can install BSM on a UNIX platform by running the applicable installer, or by using the command line. Prerequisites IMPORTANT If you are running UNIX on a 64-bit platform, you must have the 64-bit JRE. Server host(s) to be used for BSM installation meet or exceed the minimum system requirements. For more information, see Server Hardware Requirements [p. 17]. 70

71 Chapter 5 New Installations A supported database has been installed and is accessible. For more information, see Database Prerequisites [p. 25]. Before beginning installation, make sure you have 3 GB to 5 GB of disk space available in a temporary directory for the installation process, and 3 GB for the installed product.. Set the environment variable IATEMPDIR for the temporary directory before you copy files to your system. Ensure the LIBPATH environment variable for AIX is pointing to LIBPATH=/opt/Compuware/dlm/AIX/64 (or 32 depending on your platform). For SunOS use LD_LIBRARY_PATH=/opt/Compuware/dlm/ (for 32-bit) or LD_LIBRARY_PATH_64=/opt/Compuware/dlm/ (for 64-bit). The user installing and running BSM should be a non-root user and must have sys rights (be a member of the sys group). To ensure that the ulimit value allows file sizes in excess of the extracted size of install.bin, set fsize=-1 (unlimited file size) before beginning the installation. The installation program will run successfully if the JAVA_HOME directory contains jre/bin. Compuware suggests installing in console mode. NOTE When installing BSM on Solaris or AIX, you must: Set the JAVA_HOME environment variable and add JAVA_HOME/bin as the first java in the PATH before performing the installation. For example: JAVA_HOME=/opt/compilers/java/<java version>;export JAVA_HOME PATH=/opt/compilers/java/1.5.14/bin:$PATH;export PATH Install the Configuration Client on a Windows or Linux platform, as the client is not supported on Solaris or AIX. Use the Custom installation option to install the Service Model server and Dashboard on a Solaris or AIX platform, then use the Client option to install the Configuration Client. 1. Connect to your installation host with the user name that owns the installation. 2. Create a temporary directory. 3. Copy the installation file appropriate for your platform (located on DVD 3 of the Gomez distribution, in the Business Service Manager\[platform]\ folder) to a temporary directory, give the file executable permissions, and execute. chmod +x install.bin For text-only installation, which prompts for input on the console, use the command./install.bin -i console CAUTION If you install BSM through the GUI installer, the temporary directory must not contain the installer.properties or install.properties files before you begin installation. 71

72 Chapter 5 New Installations 4. Follow the prompts to configure: a. Where you want to install BSM components. b. What kind of installation you want (Standard, Client, Connection Manager, Custom). The options are similar to a Windows installation. 5. After the main installation process is completed, start the Setup Wizard manually by entering the following commands:./bsm_home/bin/presetup.sh./bsm_home/bin/setup 6. Configure the following: a. Host name for database(s), database user ID and password. b. Change the permissions of the ICMP server executable as displayed in the prompt. c. Identify the installation directory where the DLM application will install the product license. d. Verify or change the default port assignments. 7. To verify your installation, start BSM by executing BSM_HOME/bin/StartServer.sh. If BSM services start up, you have installed successfully. You are ready to configure the application server. For more information, see Configuring the Application Server [p. 76]. UNIX Remote Silent-Mode Install Without X Server You can perform a remote UNIX installation even when the target machine is not running with X server operations. This installation requires an install.properties file on the target machine. It is recommended that you verify that X server operations are definitely not available. 1. Log in to the UNIX target host using putty or some similar utility. 2. Configure the install.properties file and follow the general procedures described for Windows batch-mode installation. For more information, see Windows Command-Line Installation [p. 70]. To start the silent mode installation, use the command./install.bin -i silent 3. Start the Service Model server and Apache Tomcat server on the UNIX host, using the StartAll script. 4. From a remote machine, log in to the Configuration Client and the Dashboard on the UNIX host to make sure they run correctly and in particular that graphs can be displayed correctly. Properties File for Command-Line Installation The properties file used by the installation and setup is a standard Java properties file, java.util.properties. 72

73 Chapter 5 New Installations The format of this properties file is Property=value Property=value... Multi-line values are not supported. There is no requirement to use escape codes for characters such as spaces and tabs. A line beginning with # is a comment. Installing on Linux This procedure is for new installations on Linux RedHat environments. Prerequisites Host machines(s) to be used for BSM installation meet or exceed the minimum system requirements. For more information, see Server Hardware Requirements [p. 17]. A database has been installed and is accessible. For more information, see Database Prerequisites [p. 25]. Ensure the LD_LIBRARY_PATH environment variable is pointing to LD_LIBRARY_PATH=/opt/Compuware/dlm/ (for 32-bit platforms) or LD_LIBRARY_PATH_64=/opt/Compuware/dlm/ (for 64-bit). 1. Create a temporary directory where you have at least 3 GB to 5 GB of space for the installation process and 3.1 GB for the installed BSM. 2. Set the environment variable IATEMPDIR for that temporary directory. 3. On the Gomez media, on DVD 2, locate and execute the Linux installation file: Business Service Manager/[Linux platform type]/install.bin. 4. Follow the prompts to configure: a. Where you want to install BSM components. b. What kind of installation you want (Standard, Client, Connection Manager, Custom). The options are similar to a Windows installation. 5. After the main installation process is completed, start the Setup Wizard manually by entering the following commands:./bsm_home/bin/presetup.sh./bsm_home/bin/setup 6. Configure the following: a. Host name for database(s), database user ID and password. b. Change the permissions of the ICMP server executable as displayed in the prompt. c. Identify the installation directory where the DLM application will install the product license. d. Verify or change the default port assignments. You are ready to configure the application server. For more information, see Configuring the Application Server [p. 76]. 73

74 Chapter 5 New Installations 74

75 CHAPTER 6 Post-Installation Tasks After installing Business Service Manager, you must configure the installation and confirm that it is working properly. You may also need to perform other post-installation procedures, depending on how you are deploying BSM and its database in your enterprise. Database setup Details of post-installation checks to be conducted may depend on the database you have installed. You may need to start the server to conduct some of these checks and procedures. For more information, see Configuring the Database [p. 26]. Firewalls A number of TCP connections are used by the Service Model server, the Configuration Client, the Web server, and the database. All communication between these components are carried out over TCP to ensure reliable transport. For more information, see Port Settings [p. 54]. Adaptor setup When you establish interfaces with various tools and adaptors, you may need to perform specific procedures to ensure that the interface is established and working correctly. UNIX Permissions After BSM installation, make sure the required UNIX permissions exist. The Connection Manager uses the PingServer executable for network connections. UNIX requires that the PingServer process has permissions to write to raw sockets. The ping executable must be owned by root and must have the set user ID on execution (setuid) flag set. To set permissions: 1. Make sure you are the root user. 2. Run the following script: BSM_HOME/bin/SetPingPermissions.sh 75

76 Chapter 6 Post-Installation Tasks Configuring the Application Server The topics in this section describe the procedures for configuring the supported application servers for Business Service Manager. You must install a Dashboard application server (Tomcat, WebLogic or WebSphere) prior to configuring it. If you are using Sun ONE as your application server, obtain installation and configuration notes from Compuware Customer Support. Apache Tomcat Configuration To use HTTPS operations on your Apache Tomcat server for BSM, you must generate SSL keys and certificates, configure both the Apache Tomcat server and Service Model server to use SSL, configure your JRE to work with Tomcat, and restart your system. Refer to the Apache Tomcat documentation for instructions on configuring Tomcat performance. Refer also to the catalina.ext file for your system (catalina.bat for Windows or catalina.sh for UNIX) in the BSM_HOME/tomcat/bin directory. You can obtain information on issues like memory size settings from the Tomcat FAQs. For settings specific to BSM interaction with Tomcat, refer to notes provided in the file BSM_HOME/tomcat/webapps/centauri/WEB-INF/MainServletProperties.xml. The default BSM user is VSMUSR_TOMCAT and the default password is CHangeitTEMP1. The password is set to never expire. Generating Keys and Certificates You must generate an SSL key and associated certificate for Apache Tomcat, to protect communication. Perform the following steps on the machine used to run the Service Model server: 1. Open a command prompt. 2. Run the appropriate command. Windows set PATH=BSM_HOME\jre\bin;%PATH% UNIX export PATH=BSM_HOME/jre/bin:$PATH 3. Create the key. Using the keytool provided with the JRE shipped with BSM, execute the following: keytool -genkey -alias tomcat -keyalg RSA -keystore file -validity days where file is the file in which to store the key and days is the number of days for which the key is valid. 4. Provide the domain name. In answer to the prompt What is your first and last name? enter the fully qualified domain name of the Tomcat server. The other details are less important, but try to answer them as accurately as possible. 76

77 Chapter 6 Post-Installation Tasks 5. Provide a password. To use the keystore as the password, press [Enter] in response to the prompt, Enter key password for <tomcat>. The keystore and the key password must be the same. For example, you want a new key for the Tomcat server abc.example.com and you want the key to be valid for 365 days. You want to store it in the file C:\temp\tomcat.keystore and protect it with the password qwerty. The following example shows the session for this scenario. c:\>keytool -genkey -alias tomcat -keyalg RSA -keystore c:\temp\tomcat.keystore -validity 365 Enter keystore password: qwerty What is your first and last name? [Unknown]: abc.example.com What is the name of your organizational unit? [Unknown]: Development What is the name of your organization? [Unknown]: Example Pty. Ltd. What is the name of your City or Locality? [Unknown]: Sydney What is the name of your State or Province? [Unknown]: NSW What is the two-letter country code for this unit? [Unknown]: AU Is CN=abc.example.com, OU=Development, O=Example Pty. Ltd., L=Sydney, ST=NSW, C=AU correct? [no]: yes Enter key password for <tomcat> (RETURN if same as keystore password): 6. Export the certificate for the newly generated key. Execute the following command: keytool -export -alias tomcat -keystore keystore -file cert where keystore is the file where the key is stored and cert is the file where the certificate is stored. You are prompted for the password you entered when you created the keystore. This certificate is used later when you configure the JRE in which BSM runs. For more information, see Configuring the Java Runtime Environment [p. 78]. For the example in Step 3 [p. 76], use the following command to export the certificate to the file tomcat.cer: keytool -export -alias tomcat -keystore c:\temp\tomcat.keystore file c:\temp\tomcat.cer Configuring the Apache Tomcat Server The default configuration file that ships with Tomcat already has a connector tag for the secure socket, but it is commented out by default. You need to add a secure socket for SSL in tomcat/conf/server.xml. 1. Remove the comment tags around: <-- Define a SSL Coyote HTTP/1.1 Connector on port > <!-- <Connector port="8443" minprocessors="5" maxprocessors="75" enablelookups="true" disableuploadtimeout="true" acceptcount="100" debug="0" scheme="https" secure="true"; 77

78 Chapter 6 Post-Installation Tasks --> clientauth="false" sslprotocol="tls"/> 2. Add an attribute called keystorefile that specifies the full path to the keystore file created in Generating Keys and Certificates [p. 76]. Note that the values are case-sensitive and must match the exact case. 3. Add an attribute called keystorepass that contains the password used to secure the keystore file created previously. 4. Set the port to the desired secure socket if different from the default (8443). If you are not using the default port, you will also need to update the redirectport in the non-ssl socket connector tag for port Configuring the Java Runtime Environment Each Java Runtime Environment (JRE) that hosts a BSM component must be configured to trust the secured Tomcat server. This is particularly important for the JREs used to run the Service Model server (BSM_HOME/jre) and the Configuration Client. The following procedure assumes that you have already generated a certificate from the key used on the Tomcat server and that the JRE you are to configure is located in JRE_HOME. For more information, see Generating Keys and Certificates [p. 76]. 1. Import the Tomcat certificate into the JRE. Execute the following command as one line: JRE_HOME\bin\keytool -import -keystore JRE_HOME\lib\security\cacerts -file tomcat.cert -alias tomcat.cert The default password for cacerts is changeit. 2. When prompted to Trust this certificate, type yes and press [Enter]. The following is an example session for importing the certificate from the example into a JRE located in C:\BSM_HOME\jre. c:\bsm_home\jre\bin\keytool -import -alias tomcat -keystore c:\bsm_home\jre\lib\security\cacerts -file c:\temp\tomcat.cer Enter keystore password: changeit Owner: CN=abc.example.com, OU=Development, O=Example Pty. Ltd., L=Sydney, ST=NSW, C=AU Issuer: CN=abc.example.com, OU=Development, O=Example Pty. Ltd., L=Sydney, ST=NSW, C=AU Serial number: 42af6557 Valid from: Wed Jun 15 09:16:39 EST 2009 until: Thu Jun 15 09:16:39 EST 2010 Certificate fingerprints: MD5: E2:A7:1B:C3:71:0D:32:DE:DD:26:A4:B5:3A:20:FA:53 SHA1: 4F:30:46:76:BD:34:01:71:95:C1:15:52:F0:28:08:BC:1E:66:B0:44 Trust this certificate? [no]: yes Certificate was added to keystore Restart After configuring Apache Tomcat, restart the Service Model server, the Apache Tomcat server (Gomez Reporting Portal service), and any open Configuration Client to ensure that they all use the correct keys and certificates. 78

79 Chapter 6 Post-Installation Tasks You must connect to Tomcat using its fully qualified domain name. This is important because Web browsers and BSM make sure that the host in the URL matches the name in the key and certificate used to secure the connection. You may get a message similar to the following when connecting to the Apache Tomcat server. A warning may appear when you run some of the applets off the dashboard, for example the Reports tree, when the JRE running the applet does not trust the unverified Tomcat certificate. To resolve this issue, add the certificate to the list trusted by the JRE running the applet. The message appears when the browser does not trust the Tomcat certificate. To resolve this issue, add Tomcat s certificate to your browser s list of trusted certificates. WebSphere Configuration Prerequisites It is assumed that a supported version of WebSphere Application Server is already installed. These instructions describe deploying BSM to WebSphere Application Server V7 ( ) after installing the Dashboard server component. For more information, see Supported Application Servers [p. 22]. Remember to first shut down the default Tomcat server, if it was installed, configured and started during the installation process. Prepare for Deployment of the Context-Sensitive Help Provider By default, the BSM Dashboard connects to the context sensitive help provider via port To modify this setting perform the following: 1. Edit the main servlet properties file: BSM_HOME/tomcat/webapps/centauri/WEB-INF/MainServletProperties.xml 2. Locate the <CSHProvider> tag and modify the port number on the <Server> element to the correct value for your application server configuration: <Server>somehost:9080</Server> Prepare the Application WAR Files 1. The BSM Dashboard Deployment Utility script needs the location of a proper Java runtime environment. If you do not have a system JAVA_HOME environment variable defined, edit this setting in the script: a. Edit the deployment utility script file: BSM_HOME/misc/webapp/bin/deploy-utility.cmd or BSM_HOME/misc/webapp/bin/deploy-utility.sh b. Modify JAVA_HOME for your environment. 2. Run the BSM Dashboard Deployment Utility to prepare the application WAR files for deployment. The deployment utility updates property files configured during the installation process, containing the location of the Service Model server, database and WebSphere plug-ins deploy directory: 79

80 Chapter 6 Post-Installation Tasks Navigate to BSM_HOME/misc/webapp/bin and execute deploy-utility.cmd or deploy-utility.sh. 3. The deployment utility is implemented as a simple GUI wizard. Follow the steps: a. Select the application server and version of the deployment. b. Select the base webapp/ directory. The deploy utility depends on a specific directory structure. If you invoked the script from BSM_HOME/misc/webapp/bin, this is already set for you. While the WAR file update is in progress, you may click Cancel at any time to abort the operation. c. Select Finish button to exit the deploy utility. Prepare the WebSphere Runtime Environment 1. Using the Profile Management Tool, create a new WebSphere runtime environment, or use the default initial profile created during installation. For example, create PROJECT_ROOT/IBM/WebSphere/AppServer/profiles/AppSrv Shut down the WebSphere server, if it was started after creating the initial profile. 3. Create the LIFERAY_HOME/ directory for plugin deployments. It is located in the home directory for the server process. For default Windows installations, use the following commands: Windows Service: mkdir C:/WINDOWS/system32/config/systemprofile/liferay Non-Windows service: mkdir C:/Documents and Settings/Administrator/liferay 4. Create the Liferay Portal data and deploy directories containing the BSM default dashboards and deployable plug-ins in LIFERAY_HOME/. a. Copy BSM_HOME/misc/webapp/data to LIFERAY_HOME/data. b. Copy BSM_HOME/misc/webapp/deploy to LIFERAY_HOME/deploy. 5. Create the Liferay Portal staging directory for plugin deployments in LIFERAY_HOME/: mkdir C:/WINDOWS/system32/config/systemprofile/liferay/websphere-deploy 6. Copy the BSM external libraries to the WebSphere runtime environment. Copy the contents of BSM_HOME/misc/webapp/lib to PROJECT_ROOT/IBM/WebSphere/AppServer/lib/ext. 7. For WebSphere 6 installations only; if you are using WebSphere 7, you can proceed to Step 10 [p. 81]. WebSphere 6.x contains older versions of the portlet.jar that must be overwritten. Copy BSM_HOME/misc/webapp/lib/portlet.jar to: PROJECT_ROOT/IBM/WebSphere/AppServer/java/jre/lib/ext. 8. For WebSphere 6 installations only: the BSM dashboard on WebSphere 6 needs newer versions of the JavaScript and XML libraries. To resolve this, copy the BSM_HOME/misc/webapp/endorsed directory to: PROJECT_ROOT/IBM/WebSphere/AppServer/java/jre/lib/endorsed. 9. For WebSphere 6 installations only; if you are using WebSphere 7, you can proceed to Step 10 [p. 81]. The WebSphere 6 Web Container throws a FileNotFoundException when a request is received for a static file that does not exist on the file system despite a 80

81 Chapter 6 Post-Installation Tasks called filter handling the request and not calling the next filter in the chain. To correct this issue, create a new Web Container custom property: a. Start the WebSphere Application Server and browse to the Admin console. b. Enter the URL If necessary, change localhost to the hostname or IP address for the server and change 9043 to the correct port. c. In the left-hand tree, expand the Servers node; and click Application Servers. d. For default installations, select server1. e. Ensure that the Configuration tab is active, then expand Web Container Settings. f. Click Web container. g. Under Additional Properties, click Custom Properties. h. Click New. i. In the Name field, enter the following: com.ibm.ws.webcontainer.invokefilterscompatibility. j. In the Value field, enter true. k. (Optional) In the Description field, add the following comment: Filter chain fix. l. Click Apply to save your changes. 10. Modify the WebSphere Application Server startup parameters. a. Start the WebSphere Application Server and browse to the Admin console. b. In the left-hand tree, expand the Servers node; then expand the Server Types node. c. In the left-hand tree, click WebSphere application servers. d. For default installations, select server1. e. Ensure that the Configuration tab is active, then expand Java and Process Management. f. Click Process definition. g. Click Java Virtual Machine. h. In the Initial heap size field, enter i. In the Maximum heap size field, enter j. In the Generic JVM arguments field, add the following: Dfile.encoding=UTF8 Dvantage.controller=liferay. k. Click Apply to save your changes. l. Shut down the WebSphere Application Server. 11. If necessary, uninstall the default application for the profile a. Start the WebSphere Application Server and browse to the Admin console. b. In the left-hand tree, expand the Applications node, then expand the Application Types node. c. In the left-hand tree, click WebSphere enterprise applications. d. Select Default Application and click Uninstall. e. Click OK to remove the application. f. Click the Save link to save the changes to the location application. Deploy the WAR Files to WebSphere 1. Deploy the liferay-portal.war file using the WebSphere Integrated Solutions Console. a. Start WebSphere Application Server and browse to the Admin console. 81

82 Chapter 6 Post-Installation Tasks b. In the left-hand tree, click Applications. c. In the left-hand tree, click New Application. d. Click New Enterprise Application. e. With the Local file system button selected, click Browse, and navigate to BSM_HOME/misc/webapp and select liferay-portal.war. f. Click Next. g. Ensure the Fast Path - Prompt only when additional information is required button is selected and click Next. h. Click Next. i. Select the liferay-portal Module and click Next. j. Select the liferay-portal Web module and click Next. k. In the Context Root field, enter / and click Next. l. On the Summary page, click Finish. m. Click the Save link to save the changes to the local configuration. n. In the left-hand tree, click Applications. o. In the left-hand tree, click Application Types. p. In the left-hand tree, click WebSphere enterprise applications. q. In the Enterprise Applications page, select liferay-portal war and click Start. r. Verify that the Application Status field has a green arrow. NOTE This installation may take a few minutes, so please be patient. This is because the Liferay autodeployer will also preprocess and prepare all of the BSM plug-in components contained in the LIFERAY_HOME/deploy/ directory for deployment. After preprocessing, the plug-in components are copied to LIFERAY_HOME/websphere-deploy. 2. Repeat the above steps for the other web applications in the following order: a. For tunnel-web.war, in the Context Root field, enter /tunnel-web. b. For centauri.war, in the Context Root field, enter /centauri. c. For cwinfocenter.war, in the Context Root field, enter /cwinfocenter. 3. Repeat the above steps for each of the plugin themes, layout templates and portlets in the LIFERAY_HOME/websphere-deploy directory as in the following example: For the LoginPage-theme.war, in the Context Root field, enter /LoginPage-theme. NOTE WebSphere does not have an auto-deploy feature, so each file must be deployed separately. This process may take a few minutes, so please be patient. If the deployments were successful, the BSM Dashboard can be accessed via the URL where host is the hostname or IP address where the WebSphere Application Server is installed, and port is the port WebSphere is listening on. The default value is: 82

83 Chapter 6 Post-Installation Tasks WebLogic Configuration Prerequisites It is assumed that a supported version of WebLogic Application Server is already installed. These instructions describe deployment to WebLogic Server 11gR1 (10.3.3) after the Dashboard server component has been installed. For more information, see Supported Application Servers [p. 22]. Remember to first shut down the default Tomcat server, if it was installed, configured and started during the installation process. Prepare for Deployment of the Context-Sensitive Help Provider By default, the BSM Dashboard connects to the context sensitive help provider via port To modify this setting perform the following: 1. Edit the main servlet properties file: BSM_HOME/tomcat/webapps/centauri/WEB-INF/MainServletProperties.xml 2. Locate the <CSHProvider> tag and modify the port number on the <Server> element to the correct value for your application server configuration: <Server>somehost:7001</Server> Prepare the Application WAR Files 1. The BSM Dashboard Deployment Utility script needs the location of a proper Java runtime environment. If you do not have a system JAVA_HOME environment variable defined, edit this setting in the script: a. Edit the deployment utility script file: BSM_HOME/misc/webapp/bin/deploy-utility.cmd or BSM_HOME/misc/webapp/bin/deploy-utility.sh b. Modify JAVA_HOME for your environment. 2. Run the BSM Dashboard Deployment Utility to prepare the application WAR files for deployment. The deployment utility updates property files configured during the installation containing the location of the Service Model server, database and the WebLogic plug-ins deploy directory. It also updates the web archives with the proper WebLogic deployment descriptors. Navigate to BSM_HOME/misc/webapp/bin and execute deploy-utility.cmd or deploy-utility.sh. 3. The deployment utility is implemented as a simple GUI wizard. Follow the steps: a. Select the application server and version of the deployment. b. Select the base webapp/ directory. The deploy utility depends on a specific directory structure. If you invoked the script from BSM_HOME/misc/webapp/bin, this is already set for you. While the WAR file update is in progress, you may click Cancel at any time to abort the operation. 83

84 Chapter 6 Post-Installation Tasks c. Select Finish button to exit the deploy utility. Preparing the WebLogic Domain 1. Using the WebLogic Configuration Wizard, create a new WebLogic domain. For example, create: PROJECT_ROOT/user_projects/domains/vsmdashboard_domain. 2. Shut down the WebLogic server if it was started after creating the domain. 3. By default, the LIFERAY_HOME/ directory is defined as the parent of the vsmdashboard_domain/ directory. Create the Liferay Portal data and deploy directories containing the default Gomez dashboards and deployable plug-ins in LIFERAY_HOME/: a. Copy BSM_HOME/misc/webapp/data to PROJECT_ROOT/user_projects/domains/data. b. CopyBSM_HOME/misc/webapp/deploy to PROJECT_ROOT/user_projects/domains/deploy. NOTE There is a defect in WebLogic Server 10.0 MP2 and earlier which throws a NullPointerException when setting the response character encoding. If you are deploying to one of these versions, you will need to run the Smart Update tool to download and install the proper patch for the WebLogic domain. SmartUpdate-ID_PW MP3 SIA6 JEVYSFG6 SmartUpdate-ID_PW MP1 ZVMK WMJ52C41 SmartUpdate-ID_PW MP2 Y2T7 NHD2CBDV 4. Create the Liferay Portal staging directory for plug-in deployments in LIFERAY_HOME\: mkdir PROJECT_ROOT/user_projects/domains/weblogic-deploy 5. Copy the main web application plugins to a temp directory within the new WebLogic domain's directory. mkdir PROJECT_ROOT/user_projects/domains/vsmdashboard_domain/temp Copy centauri.war, cwinfocenter.war, liferay-portal.war and tunnel-web.war to PROJECT_ROOT/user_projects/domains/vsmdashboard_domain/temp. 6. Modify the WebLogic Server startup parameters within setdomainenv.cmd (or for UNIX, setdomainenv.sh): NOTE The following instructions use Windows command syntax; for UNIX, use applicable syntax where needed. a. Edit the domain environment script: PROJECT_ROOT/user_projects/domains/vsmdashboard_domain/bin/setDomainEnv.cmd b. Modify the last occurrence of JAVA_OPTIONS and add the following: set JAVA_OPTIONS=%JAVA_OPTIONS% Dfile.encoding=UTF8 Dvantage.controller=liferay. c. Modify the minimum JVM heap size for all occurrences of -Xms with a value of 1024m: 84

85 Chapter 6 Post-Installation Tasks set WLS_MEM_ARGS_64BIT=-Xms1024m -Xmx1024m set WLS_MEM_ARGS_32BIT=-Xms1024m -Xmx1024m d. Modify the maximum JVM heap size for all occurrences of -Xmx with a value of 1024m: set WLS_MEM_ARGS_64BIT=-Xms1024m -Xmx1024m set WLS_MEM_ARGS_32BIT=-Xms1024m -Xmx1024m e. Modify the JVM perm size for all occurrences of -XX:PermSize with a value of 256m: set MEM_PERM_SIZE_64BIT=-XX:PermSize=256m set MEM_PERM_SIZE_32BIT=-XX:PermSize=256m f. Modify the JVM max perm size for all occurrences of -XX:MaxPermSize with a value of 256m: set MEM_MAX_PERM_SIZE_64BIT=-XX:MaxPermSize=256m set MEM_MAX_PERM_SIZE_32BIT=-XX:MaxPermSize=256m 7. For WebLogic 9/10.0 installations only: the BSM dashboard needs newer versions of the JavaScript and XML libraries. To resolve this, copy the BSM_HOME/misc/webapp/endorsed directory to JAVA_HOME/jre/lib/endorsed. Deploy the WAR files to the WebLogic Domain 1. Deploy the liferay-portal.war file using the WebLogic Administration Console. a. Start the WebLogic Server and browse to the Administration Console. b. Enter the URL If necessary, change localhost to the hostname or IP address for the server and change 7001 to the correct port. c. Under the Domain Structure tree, select Deployments. d. Click Install. e. Under the Current Location breadcrumb, navigate to PROJECT_ROOT/user_projects/domains/vsmdashboard_domain/temp. f. Select liferay-portal.war and click Next. g. Ensure that Install this deployment as an application is selected and click Next. h. Keep the defaults and click Next. i. Click Finish. j. Click Save. 85

86 Chapter 6 Post-Installation Tasks NOTE This installation may take a few minutes, because the Liferay autodeployer will also preprocess and prepare all of the BSM plug-in components contained in the PROJECT_ROOT/user_projects/domains/deploy directory for deployment. After preprocessing, the plug-in components are copied to PROJECT_ROOT/user_projects/domains/weblogic-deploy. Also be aware that if Configuration editing is not enabled in the WebLogic Administration Console, you may have to click Lock & Edit before beginning the procedure, and then select Activate Changes to store the configuration changes and activate the deployment. When the Liferay autodeployer has finished, it may be the case that custom-layouttpl.war and vantage-integrationportlet.war were not deployed. If this is the case, move these war files to PROJECT_ROOT/user_projects/domains/vsmdashboard_domain/temp and repeat Step 1 [p. 85] for these two web applications. 2. Repeat Step 1 [p. 85] for the other web applications in the following order: a. tunnel-web.war Supports accessing the Liferay Portal services remotely. b. centauri.war The main Gomez Dashboard application. c. cwinfocenter.war The Gomez Dashboard online help application. 3. Repeat Step 1 [p. 85] for each of the plugins themes, layout templates, and portlets in the LIFERAY_HOME/weblogic-deploy/ directory, following the example in LoginPage-theme.war. NOTE WebLogic does not support the auto-deploy feature in production mode, so each file must be deployed separately. This process may take a few minutes, so please be patient. If you are running the server in development mode, you can still use the auto-deploy feature. Copy the contents of PROJECT_ROOT/user_projects/domains/weblogic-deploy to PROJECT_ROOT/user_projects/domains/vsmdashboard_domain/autodeploy. If the deployments were successful, the Gomez Dashboard can be accessed via the URL where host is the hostname or IP address where WebLogic Server is installed, and port is the port on which WebLogic is listening. the default value is: 4. Restart the WebLogic server to complete integration of the web applications, plugin themes, layout templates and portlets. Database Archiving Options If you intend to use the default archiving method employing a separate archiving database, perform the Database Archiving Options procedure. 86

87 Chapter 6 Post-Installation Tasks 1. Establish the new archiving database with the same permissions as your main system database. 2. Create tables within the new database that have the same schemas as those used in your main system database. 3. Create proxy tables within your main system database that map to the associated tables in the archiving database. For more information, see Data Purging and Archiving in the Business Service Manager Administration Guide. Archiving Plugin Configuration For customized archiving methods, perform the following steps: 1. Add a new section to the file BSM_HOME/vsm/config/plugins/server/Archiving.xml for the archiving class (server side) you have coded. <Plugin> <Interface> com.proxima.centauri.datamanagement.archiving.archiverfactory </Interface> <Implementation> [your package.class name here] </Implementation> </Plugin> NOTE The interface specification above is standard; all archiving classes must implement it. 2. Add a new section to the file BSM_HOME/vsm/config/plugins/client/archivingUI.xml for the class that represents the user interface for your plugin archiver; i.e., the class that extends JPanel. <Plugin> <Interface> [your package.class name here] </Interface> <Implementation> [your package.class name here] </Implementation> </Plugin> 3. Update your server classpath with the.jar files that hold your new archiver. Checking Directory Contents The UNIX Directory Structure and Windows Directory Structure tables list the details of the Gomez directory structure for UNIX and Windows environments. Some knowledge in this area may be helpful in tuning, administering, or troubleshooting your system. Knowing what is normal in your system is useful if problems occur and you need to determine the cause. Unusual configurations may indicate the source of your problem very quickly. In particular, it is recommended that you review the existing.properties files in these areas. 87

88 Chapter 6 Post-Installation Tasks Table 13. UNIX Directory Structure BSM_HOME /bin /lib /jre /jre/bin /jre/lib /config /misc /tmp /tomcat/webapps/centauri /vsm/config Server and client executables Java libraries Java Runtime Environment ($JAVA_HOME) The jre directory is installed on Linux platforms only, not on AIX or Solaris. Java runtime executables Java common libraries Client configuration files Additional adaptor information and files Log files and temporary files Web files (including custom dashboards) Server configuration files Table 14. Windows Directory Structure BSM_HOME \bin \lib \jre \jre\bin \jre\lib \config \misc \tmp \tomcat\webapps\centauri Server and client executables Java libraries Java Runtime Environment (%JAVA_HOME%) Java runtime executables Java common libraries Client configuration files Additional adaptor information and files Log files and temporary files Web files (including custom dashboards) 88

89 Chapter 6 Post-Installation Tasks \vsm\config Server configuration files Starting and Stopping the Service Model Server Starting the Service Model Server on UNIX To start the Service Model server, execute the shell script BSM_HOME/bin/StartServer.sh It is recommended that you add the BSM_HOME/bin directory to your shell PATH variable. To make this change permanent, add it to the BSM users login script. For Bourne or Korn shell users, edit the $HOME/.profile to add the following line: PATH=$PATH:BSM_HOME/bin ; export PATH Shutting Down the Server on UNIX To stop the Service Model server, execute the shell script: BSM_HOME/bin/StopServer.sh. Starting the Service on Windows Use Control Panel Administrative Tools Services to start services on Windows. The simplest method of starting either the Gomez Service Model 11.7 service or the Tomcat Web server is via the Services window: 1. From the Start menu, select Control Panel Administrative Tools Services. 2. Select Gomez Service Model 11.7 or Gomez Reporting Portal 11.7, as needed. 3. Click Start. You can also start the Service Model server and the Tomcat Web server as services via the DOS command line: net start 'Gomez Service Model 11.7' net start 'Gomez Reporting Portal 11.7' Stopping the Service on Windows Use Control Panel Administrative Tools Services to stop services on Windows. Prerequisites To shut down the server, you need to have the relevant permissions. You may be prompted to log in as a user authorized to shut down the server before this action can be taken. When you have started the Tomcat Web server as a service, you should only stop it using the Services Controller or with the DOS command net stop 'Gomez Reporting Portal 11.7'. Do not use the batch file StopTomcat.bat to stop Tomcat while it is running as a service; doing so can leave the service in a confused state. Only use the batch file if you have started Tomcat with the StartTomcat.bat batch file. 89

90 Chapter 6 Post-Installation Tasks 1. From the Start menu, select Control Panel Administrative Tools Services. 2. Select Gomez Service Model 11.7 or Gomez Reporting Portal 11.7 as needed. 3. Select Stop. Starting the Configuration Client Starting on UNIX To start the Configuration Client in UNIX, execute the shell script: BSM_HOME/eclipse/vsm-client. Starting on Windows Use the Start menu or the desktop icon (if one exists) to start the Configuration Client. 1. Select Start All Programs Compuware Business Service Manager Client. The Login dialog box appears. For more information, see Login [p. 90]. 2. Enter your login details. The Server Host defaults to your local host. The Server Port defaults to The default user name and password are as follows. Username admin Password admin Login To display the Configuration Client, you must log in through the Login dialog box. Select Profile After you enter information in the fields in the Login Details area, click Save profile to add the profile to the list. Subsequently, you can select a profile from the list to enter login details automatically. If you no longer need a login profile, click Remove profile to delete it. Server Host Enter the name of the machine running the instance of the Service Model server to which you want to connect. Server Port By default, this field lists the port number used in the standard Service Model server installation. It can be changed if necessary: You may need to run Gomez on a machine where the default port (5005) is already in use. You may need to run a second Service Model server on the same machine, in which case the instances must be assigned different port numbers. 90

91 Chapter 6 Post-Installation Tasks Login automatically If this option is checked, the details provided for the next login will be used automatically for future logins, skipping the login screen. NOTE If you need to log in with different details after selecting automatic login, use the Manage Login Profiles option on the Server menu in the Configuration Client. This option displays the Login dialog box so you can change the login details. Refer to the Business Service Manager Administration Guide. Starting the Web Interface The URL of the Business Service ManagerWeb interface is 1. Display the Web interface. Point your browser to where Gomez_host is the machine on which BSM is installed. For more information, see Supported Browsers [p. 23]. When the browser connects with the Web interface, the login screen appears. 2. Log in. Use the same username and password that you set within the Configuration Client under the Server User Management option. The default username is admin and the password is also admin. The BSM opening page appears. NOTE The display details you see can vary according to the permissions you have as a user and as a member of one or more domains. If there is no activity in the Web browser for 15 minutes, you are timed out and must log in again. Adaptor and Interface Settings When you establish interfaces to various tools and adaptors, perform the necessary procedures to ensure that an interface is established and working correctly. For more information, see the Adaptors and Connections section of the Gomez Service Model Data Collection User Guide. Sending MAPI Mail for Notifications Verify that Windows Messaging exists on the Service Model server and set up a profile for BSM. 91

92 Chapter 6 Post-Installation Tasks 1. Install Windows Messaging. a. Make sure Windows Messaging is installed on the Service Model server that is going to be used to send using MAPI. When Windows Messaging is installed, you should have a MAIL icon in the Control Panel. b. Set the default account for the Gomez Service Model 11.7 service from LocalSystem to a valid user with a mail profile set up. Make sure the valid user account has access to start and stop Gomez, as well as file access to the Gomez installation. 2. Set up the messaging profile. a. In the Control Panel, choose MAIL Show Profile Exchange Server. b. Check that the mailbox is set to the correct person. c. On the Advanced tab, make sure Logon Network Security is set to NT Password Authentication. 92

93 CHAPTER 7 Upgrading and Migrating Business Service Manager to Release 11.7 NOTE If you are currently running on release 11.5.x, you can install release 11.7 over your current implementation, without having to migrate data to a second location or server. For more information, see Upgrading from 11.5.x to 11.7 [p. 94]. If you are currently using release 11.1, you must install release 11.7 in another folder on the same machine, or on another server, and then migrate data to the new installation. You can migrate the Service Model and associated data to 11.7 from Vantage Service Manager The Dashboard framework changed in release 11.5, so you will need to recreate your Dashboard pages. You will be able to migrate custom datablocks from 11.1 and add them to your new Dashboard pages. Compuware suggests that you keep your current release available so you can use it as a guide when you recreate your 11.7 Dashboard pages. You also will need to have both releases running to migrate custom datablocks. Compuware recommends two basic migration scenarios: Install all Business Service Manager 11.7 components on a different machine, or multiple machines, and migrate configuration files, database, Event Console and custom Dashboard datablocks to the new machine(s). Install Business Service Manager 11.7 components on the same machine(s) as the existing installation, but in a different directory, and migrate files and custom datablocks to the new installation. You will need to change the port numbers used by BSM to use both systems at the same time. The procedures for both scenarios are basically the same. 93

94 Chapter 7 Upgrading and Migrating Business Service Manager to Release 11.7 NOTE The Service Model Templates that you used in your existing implementation will be retained in your upgraded environment. If you want to use the new default templates, after migration, you will need to deactivate your current templates, import the new default templates, and rebuild your Service Model. For more information, see Post-Migration: Using New Service Model Templates [p. 113] and Post-Migration: Adding an 11.7 Sys_Vantage Service Model Template into a Migrated Service Model Template [p. 114]. Because of the many possible variations in system configurations, this chapter can only address the most commonly known environments and recommended migration paths. For assistance with other migration scenarios, and specifically for assistance migrating from a release earlier than 11.1, contact Customer Support. Upgrading from 11.5.x to 11.7 If your current implementation of Vantage Service Manager is release or later, you can install release 11.7 over the existing installation. The installation process copies your configuration and data files to a temporary directory. These files are automatically restored to the upgraded installation so that your data and settings are preserved. Ensure that your existing database is running before starting the upgrade. 1. Connect to your installation host with the user name that owns the installation. 2. Start the installation wizard for your platform. When the message appears, Existing Product Found On Machine, click OK to proceed. 3. Follow the prompts in the installation wizard. NOTE Make sure you select the same installation folder and options as used for the original installation. For example, if you did a custom install originally, you will need to perform the same custom install while upgrading 4. On the final screen, click Install to begin the installation. Unlike the original installation, the Setup Wizard does not appear. The installer automatically detects and uses the database and connection information previously provided. A message window displays the progress of services being installed and started. The installation may take several minutes. 5. When installation has completed, click Close to close the progress window. 6. Click Done to close the installation wizard. 7. The Service Model was changed in , and If you have no customizations in your Service Model and want to rebuild your Service Model to reflect these changes, perform steps 7a through 7e. If you want to maintain your existing model, skip these steps and go to Step 8 [p. 95]. a. Stop all adaptors from collecting data. b. Delete the services in your existing Service Model. 94

95 Chapter 7 Upgrading and Migrating Business Service Manager to Release 11.7 c. Import the slamanage.xml file, located in BSM_HOME\vsm\config\ResetConfig11.7\, using the Configuration Management Wizard. Use the overwrite option. Instructions for importing files using the wizard are available in the Business Service Manager Administration Guide and online help. For more information, see Configuration Management Wizard - Import Configuration Action in the Business Service Manager Administration Guide. d. Copy updated message translators to your implementation. Navigate to the BSM_HOME\vsm\config\ResetConfig11.7\ folder. Copy ServerVantageDataCollectionSMT_MessageTranslator.xml and EUEEventsSMT_MessageTranslator.xml and paste them in the BSM_HOME\vsm\config\ folder. e. If you are using an EUE adaptor connection, go to its Applications tab and select the checkbox to Enable Software Service metrics aggregated by application. Save the connection configuration. 8. Restart the Service Model server and restart the adaptors. NOTE If you want your existing Service Model (that you customized) to be compliant with the Service Model changes through release 11.7, you can edit your Service Model to replicate those enhancements. For more information, see Editing Customized Service Models to Match Recent Release Enhancements in the Business Service Manager Service Model User Guide. Migrating from Release 11.1 Migration Prerequisites Before migrating from release 11.1 to 11.7, do the following: Deactivate connections for any End User Experience adaptors that are deployed. As a precaution, make a backup of the entire directory for the previous release before beginning a migration. Back up the existing database before beginning a migration. For details, see the documentation for your database management system. You must create a new database for the new release. You can migrate the existing database to use with the new release; however, once you use the migrated database with the new release, that database may not be used with the old release. Because you will need the database connection information during the installation process, create the new database before installing the new release. For more information, see Database Prerequisites [p. 25]. Ensure that the server hardware, operating systems and application servers meet or exceed the recommended system requirements for the new installation. For more information, see System Requirements [p. 17]. 95

96 Chapter 7 Upgrading and Migrating Business Service Manager to Release 11.7 Before beginning installation, make sure you have at least 3 GB to 5 GB of temporary disk space for the installer process and 3 GB of space for the installed Business Service Manager. You must also have established your database hostname with login information. Install the New Release Install the new release on a different machine or different folder on the same machine that hosts the current installation. For more information, see New Installations [p. 59], Installing on UNIX [p. 70], and Installing on Linux [p. 73].. Also configure servers as instructed in Configuring the Application Server [p. 76]. When the new release is installed and configured, you can proceed to migrate data. Run the Server Migration Utility The installation for the new release includes a utility for migrating the previous version of the Service Model server. Prerequisites If you installed the new release on the same machine as the previous release, confirm that the Vantage Service Model service, Vantage Dashboards service, and Web server service for the previous release are stopped. 1. If the previous Vantage Service Manager release is on a different machine than the new release, make sure the network drive is accessible. 2. Navigate to the server utility file. On the machine where Business Service Manager Release 11.7 is installed, open a command window, then navigate to the utility file: UNIX and Linux BSM_HOME/misc/migration/server/MigrateServer.sh Windows BSM_HOME/misc/migration/server/MigrateServer.bat 3. Execute the file. In UNIX, you must first provide execute permission. 4. Specify the previous release that you have installed. You can migrate to Release 11.7 from Release Specify the source directory. When prompted, enter the full path for BSM_HOME for the previous release. 6. Specify the target directory. When prompted, enter the full path for BSM_HOME for the new release. After you specify the locations of the previous and new releases, the utility does the following: 1. Stops the Release 11.7 service if necessary. 2. Backs up the files required for migration in both the source and target directories. 3. Copies the following files from the source directory to the target directory: 96

97 Chapter 7 Upgrading and Migrating Business Service Manager to Release 11.7 Connection Manager configuration file ConnectionManager.xml Adaptor Message Translator configuration files *_MessageTranslator.xml Service Templates configuration file ServiceTemplates.xml Database Filter Message Translator DatabaseFilterMT.xml User Database configuration file UserDatabase.xml Migrate Files Provide the new release with custom and third-party files, such as customized adaptors and JavaScript libraries, that were used with the previous release but are not included in the new default installation. If you used third-party libraries with the previous release, copy the files to the corresponding location in the new release. For more information, see Checking Directory Contents [p. 87]. If the previous release included custom adaptors created using the Connection Manager SDK, contact Customer Support for an updated version of that manual. Some files from the previous release cannot be copied into the new release, because overwriting the new file would destroy required information that was not contained in the previous release. If you customized any of the following files, you must manually edit the files in the new release: All BSM_HOME/bin/*.properties files Out of Order processing configuration found in BSM_HOME/vsm/config/HistoricalDataImport.xml BSM_HOME/vsm/config/Navigator.Client.xml Compare the old and new files, and edit the new file as needed to match the customized information in the previous release. CAUTION Be careful not to delete any content, or alter the content other than the custom configurations. Deprecated copies of these files are also installed in BSM_HOME/config and WEBROOT/WEB-INF/config. It is recommended that you contact Compuware Customer Support for assistance in modifying system files. If the password for the administrator login for the previous release was changed from the default, then you need to copy the password value from the migrated UserDatabase.xml to the new release's MainServletProperties.xml file 1. In BSM_HOME/vsm/config/UserDatabase.xml, find <admin> within <Users> and copy the value for Password. NOTE The password is encrypted. 97

98 Chapter 7 Upgrading and Migrating Business Service Manager to Release In WEBROOT/WEB-INF/MainServletProperties.xml, find <UserName> and <Password>. The value for <UserName> should be admin. Replace the value for <Password> with the string you copied from UserDatabase.xml. Migrate the Database The new release of Business Service Manager includes SQL scripts for migrating the database from the previous release to the database for the new release. CAUTION If errors occur during database migration, you will not be able to continue with this process. Restore the database, and contact Customer Support for assistance. 1. If necessary, stop the Vantage Dashboards and Vantage Service Model 11.x services on the previous release. 2. Back up the database for your previous release. 3. Before running the migration script, restore the database from the previous release on top of the new 11.7 database. You should have created a new database before installing the new release. 4. Find the appropriate migration script. Browse to BSM_HOME/vsm/misc/migration/database/database_type, where database_type is the database you are using: DB2, Oracle, or SQL Server. 5. Execute the script 11_to_v11.5_database_upgrade_database_type.sql on the new 11.7 database. If your database is on a remote server, you will need to copy and run the script on that server. 6. Verify the database has been correctly configured and is accessible from BSM. For more information, see Verifying the Database [p. 52]. 7. If your database is Oracle, assign the necessary permissions for this BSM release. The following permissions are required: grant create any index, create session, create table, create view, create sequence, create procedure, alter any sequence, and unlimited tablespace. For more information, see Creating a Business Service Manager Oracle User [p. 32]. 8. If you are using Tomcat as the Web server and are using a Windows Authentication trusted connection to connect to the database, run the Setup Wizard to insert the login credentials into the migrated database. Run setup from the command line. You must include the -install option, as shown: BSM_HOME\bin\setup -install In each Setup Wizard screen, accept the defaults. 9. Start the Gomez Service Model 11.7 service. 98

99 Chapter 7 Upgrading and Migrating Business Service Manager to Release 11.7 The BSM database now supports table partitioning and data compression. Partitioning and compression can be enabled on existing databases. For more information, see Database Table Partitioning and Data Compression [p. 121]. Migrating Custom Datablocks to Version 11.7 Because of a new Dashboard framework introduced in Release 11.5, if you are migrating from release 11.1, you will need to recreate your dashboards. You can migrate custom datablocks from supported previous versions. Those datablocks must be migrated before you create your dashboards in This allows you to add them to your 11.7 dashboards. Prerequisites Both Dashboard 11.7 and 11.1 installed and running. Two Tomcat (or web application) servers running. Migration of all custom datablocks. For more information, see Migrate a Custom Datablock [p. 101]. If you don't have any custom datablocks that you want to migrate, you can skip this task. As an alternative to migrating a custom datablock, if a datablock was slightly edited in 11.1, it is recommended that you make the same edits to a similar 11.7 datablock. For example, if a Service Table was copied and some changes were made to it, it may be more time-efficient to make those changes in the 11.7 datablock rather than migrating the customized version. The following steps must be completed for each dashboard. Detailed processes follow. 1. Create a dashboard. 2. Add a page to the dashboard. 3. Choose a layout for the page. 4. Add datablocks (portlets) to the dashboard page. 5. Export the dashboard to a file to save as a backup (optional). Creating a Dashboard Create custom dashboards to which you can add datablocks. 1. Click Tools Control Panel Dashboards. 2. Click Add. 3. In the Details pane, type a name for the dashboard. 4. In the Type list, choose Regular Dashboard or Location. Location is a dashboard which displays the location of Users. If Users are spread across geographical regions, select a Location and a specific region, as well as a parent dashboard under which it will reside. Typically, you will choose a Regular Dashboard. 5. Click Save on the panel to the right to save your changes; or if you want the dashboard to be a sub-dashboard under a parent dashboard, click Select, choose a parent dashboard, and click Save. 6. Add a page to your new dashboard. For more information, see Adding a Page [p. 100]. 99

100 Chapter 7 Upgrading and Migrating Business Service Manager to Release Associate a User with one or many dashboards by clicking Select. Select a dashboard from the list and it will appear in the User's dashboard list. Click Save in the User Information panel to save your changes. For more information, see Managing Users in the Business Service Manager Dashboard and Datablocks User Guide. NOTE You must add a page to, and associate a member with, your new dashboard before it will appear as a tab next to the default dashboards. Adding a Page 1. Open the dashboard in which you want to add the page. 2. Click Add Page, located at the top of all dashboards. 3. A new page field appears at the top of the dashboard. 4. Type a name for the page. 5. Click Save. Changing a Page Layout Easily change the layout of the datablocks on the page. 1. Open a page on a dashboard. 2. Click Tools Change Page Layout. 3. Select one of the many layouts provided. 4. Click Save. When the page refreshes, it will assume the layout you selected. Adding and Deleting Datablocks Create customized dashboard pages by adding datablocks. 1. Open the Dashboard. For more information, see Accessing the Dashboard in the Business Service Manager Dashboard and Datablocks User Guide. 2. Select the specific dashboard and page to which you want to add a datablock. 3. Click Tools Add Datablock. The Add Datablock window appears. 4. Click on a category to expand its list of datablocks. For default datablocks click on Gomez. The various datablock categories appear. 5. Click on a datablock in the list for a preview of the datablock. For more information, see Datablock Types in the Business Service Manager Dashboard and Datablocks User Guide. 6. Click Add or drag the datablock to the page. Deleting a Datablock To delete a datablock, select Tools Toggle Page Editing if you have not already enabled it. Click Delete on the datablock. 100

101 Chapter 7 Upgrading and Migrating Business Service Manager to Release 11.7 Export Export dashboard pages and save them to your hard drive to be imported into another dashboard. 1. Click a dashboard to export. Typically you will create a unique dashboard with pages and datablocks to export. 2. Delete any unwanted pages. Be sure to include hidden pages. 3. Click Tools Page Settings or Tools Control Panel Dashboards Actions menu Page Settings. 4. Click the Export / Import tab. 5. Type a name for the file. 6. Click Export. It is recommend that you use the default settings. 7. A Save As dialog box appears if you are using Internet Explorer. 8. Save the file to a known location. NOTE Liferay will designate an ID for the exported layout. Migrate a Custom Datablock You can migrate datablocks from Release 11.1 to Install Sun JDK. Go to and download the JDK 5.0 Update 22. a. Launch the installation program, and use the default configuration values to install the JDK to a directory of your choice. For the remainder of this document, we will refer to the directory where the JDK is installed as the Java installation directory. b. Right-click on the My Computer shortcut on your desktop and select Properties from the context menu. Within the Properties dialog, select the Advanced tab, and click Environment Variables. c. Create a new system variable named JAVA_HOME and set its value equal to the absolute path of your Java installation directory. On a default installation, this will be C:\Program Files\Java\jdk1.5.0_14. d. Edit the PATH system variable to include %JAVA_HOME%\bin. 2. Install Apache Ant 1.7.1: a. Extract the contents of this ZIP file to a directory of your choice. This will create an apache-ant folder. For the remainder of this document, we will refer to this folder as the Ant installation directory. b. Right-click on the My Computer shortcut on your desktop and select Properties from the context menu. Within the Properties dialog, select the Advanced tab, and click Environment Variables. 101

102 Chapter 7 Upgrading and Migrating Business Service Manager to Release 11.7 c. Create a new system variable named ANT_HOME and set its value equal to the absolute path of your Ant installation directory. d. Edit the PATH system variable to include %ANT_HOME%\bin. 3. Upgrade Dojo. If you have a custom widget that employs Dojo, you must upgrade Dojo to Dojo For more information, see Dojo Upgrade and Functions, Features, and Widgets [p. 107]. 4. Add the new custom datablock. Assume that the BSM installation directory is C:\Program Files\Compuware\Business Service Manager. The custom datablock is now added to the list of available datablocks (portlets) on the Add Datablock dialog box for Extract the file DashboardSDK.zip file into the BSM installation directory. 6. Modify the custom-portlet application that is shipped with the SDK to add new custom data blocks. The custom-portlet application is a shell that can be modified. By default, it contains the Service Title datablock (portlet). When you deploy this portlet application it will create a new category Custom (listing all its portlets), beneath the already existing main category Gomez. 7. Open the command prompt and type the following commands: cd DashboardSDK\plugins-sdk\portlets\custom-portlet and ant deploy. 8. This will build and deploy the custom-portlet application. After, you will be able to add all the portlets within the application as datablocks on the page. If you make further changes to the custom-portlet application, you must re-run the command: ant deploy. 102

103 Chapter 7 Upgrading and Migrating Business Service Manager to Release To add more portlets to this application, such as portlet - sample1, for example, you must modify the following files: liferay-display.xml (added line: 8) liferay-portlet.xml (added lines: 11 to 16) 103

104 Chapter 7 Upgrading and Migrating Business Service Manager to Release 11.7 portlet.xml (added lines: 56 to 104) 104

105 Chapter 7 Upgrading and Migrating Business Service Manager to Release

106 Chapter 7 Upgrading and Migrating Business Service Manager to Release 11.7 Other modification guidelines: view.url This is a mandatory parameter; it should point to the datablock controller file within the Centauri application. The path MUST NOT contain references to Centauri and MainServlet. It also MUST start with a leading forward slash - / and MUST end with.html. help.id This is not a mandatory parameter; it should contain a valid help identifier, so the appropriate help information is launced when the portlet is put into HELP mode. idatablock.description, datablock.type and datablock.image These are not mandatory parameters; information from these parameters will appear in the pop-up that list all the datablocks when you select the Add Datablock option. Porting an Existing Centauri Datablock into Liferay After creating a new custom portlet in Lifefray, you must port the datablock that serves up its content. When creating a new datablock or migrating one from a previous release, you will need to make some modifications to the XSL file that processes the HTML and data for that datablock. You will need to start using the following global XSL parameters during the transformation (these are just sample values). The theme parameters should be used to build URL links, image resources, etc., within a datablock, and the portlet parameters should be used for datablock identity information (for example, portlet.windowid is a globally unique identifier for a portlet instance, but portlet.id is a globally unique identifier for a portlet). Portlet portlet.id="vantagecustom_war_vantagecustomportlet" portlet.mode="view" portlet.view.url="/templates/datablocks/servicetitle.html" portlet.windowid="vantagecustom_war_vantagecustomportlet_instance_9fcd_layout_10483" Theme theme.chartingpath="c:/program Files/Compuware/Business Service Manager/ tomcat/webapps/vantage-default-theme/charting/color_schemes/vantage-default" theme.currentcolorscheme="vantage-default" theme.id="vantagedefault_war_vantagedefaulttheme" theme.imagepath="/vantage-default-theme/images/color_schemes/vantage-default" theme.name="vantage Default" theme.url.current="/group/operations/test?_p_id= vantagecustom_war_vantagecustomportlet_instance_9fcd&p_p_lifecycle= 0&p_p_state=normal&p_p_mode=view&p_p_col_id=column-2&p_p_col_count=1&showStep=2" theme.url.currentpath="/group/operations" theme.url.currentpathandfile="/group/operations/test" theme.url.currenturl=" theme.url.group=" 106

107 Chapter 7 Upgrading and Migrating Business Service Manager to Release 11.7 theme.url.home=" theme.url.portal=" Dojo Upgrade and Functions, Features, and Widgets Dojo Functions Review the changes to various functions, features, and widgets from Dojo to Dojo The following are specific Dojo functions that are called, along with an example of its usage and comments regarding migration. provide dojo.provide("centauri.misc.utilities"). There is no change to this. require dojo.require("dojo.widget.*") References to.* namespaces are no longer supported. See the comment below, No more.* namespace. The dojo.widget namespace is renamed to dijit. connect dojo.event.connect(window,"onload",fnc) dojo.event.disconnect( )has moved to dojo.connect() and dojo.disconnect().the after, before and around flags are no longer supported. connect() now returns a handle, which must be passed to disconnect(). There are only 3 calls to disconnect() in the code, all in the file widget\tooltip.js. byid dojo.byid("calendarbutton") dojo.widget.byid( okbutton ) dojo.widget.byid()has changed to dijit.byid() dojo.widget.getwidgetsbytype() has changed to dijit.registry.byclass(). Iterate over the results using dijit.registry.byclass(...).foreach(func). addonload dojo.addonload( initshortcutbuttonlist ) publish dojo.event.topic.publish("/serviceselections",message) dojo.event.topic.publish()becomes dojo.publish("/serviceselections",[{sm_id: theid, ServerLineName: self.serverlinename, selected:1}]) The second argument is now an arguments array that will be supplied to all subscribers subscribe dojo.event.topic.subscribe("/timenavigation", this, "handletimenavigation")is now called as dojo.subscribe, dojo.unsubscribe. subscribe()now returns a handle which is necessary to unsubscribe this listener. 107

108 Chapter 7 Upgrading and Migrating Business Service Manager to Release 11.7 debug dojo.debug("background changed") dojo.debug(), dojo.debugshallow(), and dojo.debugdeep() have been replaced by the appropriate console.* methods. addclass The following functions are now moved into dojo e.g., dojo.html.hasclass( ) ==> dojo.hasclass( ): dojo.html.addclass(cell,"servicequalitylabel") dojo.html.removeclass(this.anchornode, "selected") dojo.html.replaceclass(this.statusbartextnode, 'text_normal', 'text_error') dojo.html.hasclass(this.advancedsearchoptionsnode, "hidden") mixin dojo.lang.mixin(this.urlparameters, parameters). There is no change. define Widget dojo.widget.definewidget("centauri.widget.sparkline", dojo.widget.htmlwidget, dojo.definewidget() has been replaced by plain dojo.declare(). create Widget dojo.widget.createwidget("centauri:imageviewitem", In place of dojo.widget.createwidget(), simply use the Javascript "new" constructor: var button1 = new dijit.form.button(params, srcnoderef); where srcnoderef is a reference to an existing DOM node or ID string. The sequence of internal calls during widget creation has changed. It is possible that some of the custom widgets will need adjustment. hitch dojo.lang.hitch(this, this.datahandler). There is no change. lfx dojo.lfx.fadeout(this.domnode, 500).play() fadein() and fadeout()have moved to the base, dojo. charting new dojo.charting.plotarea().there is no change. JSON dojo.json.evaljson(this.urlparams). There is no change however, some Dojo widgets may now require a slightly different JSON format for their data inputs. In particular, the dojox.grid widget uses a highly specific data input format, and the data structure must change. fixevent dojo.event.browser.fixevent(evt) dojo.event.browser.fixevent() becomes dojo.fixevent(). bind dojo.io.bind(bind) 108

109 Chapter 7 Upgrading and Migrating Business Service Manager to Release 11.7 bind() has been replaced with more specific functions that give a better indication about which IO transport is being used. There are some adequate examples in the above-mentioned reference links. other HTML dojo.html.setstyle(this.servicetreecontentnode,"width","auto") dojo.html.getparentbytype(target, 'td') dojo.doc().createelement("img") dojo.html.placeonscreen(tmpnode, evt.pagex, evt.pagey, 0, true) Dojo Features The following are specific Dojo features used by the BSM code, along with an example of its use and comments regarding migration. djconfig Nothing notable. dojotype References to widgets use the dojotype attribute on some HTML tag. The name must be fully qualified using the Javascript package, and references are case-sensitive. XHTML-style namespaces and Dojo-specific tags are no longer supported. The following two styles of declaration in 0.4 have been replaced: <button dojotype="button"> <dojo:button> The replacement is <button dojotype="dijit.form dojoattachpoint Lists within dojoattachpoint, dojoattachevent, wairole, and waistate are now comma-separated and not separated by semi-colons. All custom widgets with children (and templates) must declare dojoattachpoint=containernode. It no longer defaults to domnode. dojo.widget Is now dijit.* namespace Mapping a.* resource name to file package.js is no longer supported. It was too much "magic", and caused confusion with the Java notion of.* in package names. So things like dojo.require("foo.*") mapping to foo/ package.js is no longer supported. Instead, use one of the following conventions: Use "common": For instance, dojo.require("foo.common") mapping to foo/common.js. Use a "private" directory: For instance, a "foo.bar" that maps to foo/bar.js, which in turn loads modules from a "private" directory named foo/_bar. Examples of this convention can be found in dojox: dojox.gfx, dojox.cometd, and dojox.sql. We only use the.* convention with these 5 namespaces: 109

110 Chapter 7 Upgrading and Migrating Business Service Manager to Release 11.7 dojo.require("dojo.event.*"):moved to base. dojo.require("dojo.html.*"):most functions moved to dijit. dojo.require("dojo.lang.*"):moved to base. dojo.require("dojo.widget.*"):moved to dijit. Dojo Widgets In Dojo 1.1.0, there are small changes to the way that widgets are declared, defined and derived. This is the short list of Dojo widgets that are used, and any notable comments for migration. dojo.widget.button Nothing notable. dojo.widget.chart Nothing notable. dojo.widget.contentpane ContentPane is dijit.layout.contentpane The ContentPane in 0.9 is stripped of some functionality. A feature-complete version is available in dojox.this widget now has a startup()method that you must call after the widget is created and you have done addchild() for all of its children. Details are available in the Dojo Porting Guide: 0.4.x to 0.9.Go to for more information. dojo.widget.dialog Nothing notable. dojo.widget.filteringtable Replaced by dojox.grid. Widget is only used in 2 modules. dojo.widget.htmlwidget Refer to renamed methods In the 0.4-to-0.9 porting guide. Widget is only used in 6 modules. dojo.widget.popupcontainer This widget may now have a startup()method that you must call after the widget is created and you have done addchild() for all of it's children. dojo.widget.popupcontainerbase Some convenient static methods within this are called. dojo.widget.resizehandle Moved to dojox.layout.resizehandle(). dojo.widget.spinner Moved to dijit.form.numberspinner Migrate the Event Console Configuration Migrate the Event Console configuration by copying the configuration details from the previous release to the new release. 110

111 Chapter 7 Upgrading and Migrating Business Service Manager to Release Open both the previous release of the Event Console and the new release. 2. Open the Preferences windows. Select Edit Preferences in each to open the Preferences window for the Event Console in both releases. 3. In the Main node, copy the values for all the fields from the previous release to the new release. For more information, see Main Category in the Event Console in the Business Service Manager Event Management User Guide. 4. Skip the Visible Columns node. The Visible Columns node cannot be migrated because the columns are only visible after new events are received. When new events that contain different parameters are received in the new Event Console, you can then choose columns as needed. 5. Set the colors in the new release. a. In the Event Colors node, change the colors for test and backgrounds to the same as the previous release. b. In the Color Rules node, add the color rules from the previous release. For more information, see Event Colors Category in the Event Console in the Business Service Manager Event Management User Guide. 6. In the Actions node, add the actions from the previous release. For more information, see Actions Category in the Event Console in the Business Service Manager Event Management User Guide. 7. In the Timers node, copy the script from previous release to new release, and then set the Interval value. For more information, see Timers Category in the Event Console in the Business Service Manager Event Management User Guide. 8. In the Advanced Filters node, add custom filters one-by-one. You cannot copy the entire expression at once; you must add the sub-expressions one-by-one. For more information, see Advanced Filters Category in the Event Console in the Business Service Manager Event Management User Guide. 9. In the Misc node, copy the values. For more information, see Miscellaneous Category in the Event Console in the Business Service Manager Event Management User Guide. Migrate Page Caching If you used page caching in the previous release, perform this task to migrate to the new release. In the steps below, WEBROOT is the application server directory: If you are using the default Apache Tomcat server, WEBROOT is BSM_HOME/tomcat/webapps/centauri. 111

112 Chapter 7 Upgrading and Migrating Business Service Manager to Release 11.7 If you are using another application server, WEBROOT is the directory created when you deployed the centauri.war file to configure the application server for Gomez. If the previous release is on a different machine than the new release, make sure the network drive is accessible before beginning the migration. 1. Convert the persisted data page cache to XML. a. Start a new application server service. It is not necessary to shut down any service that is currently running. b. Execute Xstream jar and com.compuware.frameworks.web.pagecache jar. These files are located in WEBROOT/WEB-INF/lib In the command line, specify WEBROOT/CacheConsole as the destination directory. 2. Migrate the file pagecaching.properties. If you are using Tomcat as your Web server, copy pagecaching.properties from BSM_HOME/tomcat/webapps/centauri/WEB-INF in the previous release to the same directory in the new release. If you are using another application server, you only need to copy the file if the centauri directory for the new release is different from the directory used by the previous release. 3. Open WEBROOT/CacheConsole/View/migrator.html into your browser. 4. Migrate the caching rules. Click the appropriate Caching Rules Migration option, then click Convert Rules. 5. Select the appropriate Cached Pages Migration option. 112

113 Chapter 7 Upgrading and Migrating Business Service Manager to Release Identify the source directory. In the Folder field, type the directory path for the cached pages in the previous release. 7. Migrate the cached pages. Select Load names of serialized cached pages, then select Start. The migrated cache will be persisted in the database the next time persistency is processed. Post-Migration: Using New Service Model Templates The Service Model Templates that you used in your existing implementation will be retained in your upgraded environment. The default Service Model Templates introduced in release 11.1, Sys_VantageGlobal and Sys_VantageAlerts, were replaced in 11.5 with six smaller templates. Four of the new default templates are not compatible with Service Models built from older Vantage templates. If you want to use the new default templates, recommended for users upgrading to Gomez 11.7 monitoring solutions, you will need to rebuild your Service Model with the new templates after upgrading BSM and the Central Analysis Server to You should also upgrade your Gomez monitoring products before using the new templates. Two of the new templates, Sys_VantageVirtualization and Sys_VantageMainframe, offer new functionality that won't conflict with older templates. If you don't want to rebuild your Service Model using all of the new templates, you can manually add these two to your migrated templates. For more information, see Post-Migration: Adding an 11.7 Sys_Vantage Service Model Template into a Migrated Service Model Template [p. 114]. To rebuild your Service Model with the new templates, post-migration: 1. Close all adaptor connections. 2. Deactivate the templates used from the previous release. 113