Envinsa INSTALL GUIDE. Version 4.1. For WebSphere Application Servers

Transcription

1 Envinsa Version 4.1 INSTALL GUIDE For WebSphere Application Servers

2 Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor or its representatives. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, without the written permission of MapInfo Corporation, One Global View, Troy, New York MapInfo Corporation. All rights reserved. MapInfo, the MapInfo logo and Envinsa are trademarks of MapInfo Corporation and/or its affiliates. MapInfo Corporate Headquarters: Phone: Fax: Sales: Government Sales: Technical Support: MapInfo UK and EMEA Headquarters: Phone: Fax: Technical Support: MapInfo Asia Pacific Headquarters: Phone: Fax: Technical Support: Contact information for all MapInfo offices is located at: Copyright 2006 The Legion Of The Bouncy Castle Copyright IPDR Organization All Rights Reserved Copyright 2006, International Business Machines Corporation and others. All Rights Reserved. Copyright 2006 Open GIS Consortium, Inc., All Rights Reserved. Copyright 2006 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved. This product includes software developed by the Apache Software Foundation ( Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Adobe Acrobat is a registered trademark of Adobe Systems Incorporated in the United States. Products named herein may be trademarks of their respective manufacturers and are hereby recognized. Trademarked names are used editorially, to the benefit of the trademark owner, with no intent to infringe on the trademark. February 9, 2007

3 Table of Contents Chapter 1: Requirements Release Notes and Envinsa Documentation System Requirements Supported Software Chapter 2: Preinstallation Tasks Install Application Server Instances Tasks Set Default JVM Heap Sizes Remove Conflicting jdom.jar File Create a Directory for Installer Log Files Start Application Server Instances Recommendations Services Data Components Decide on Installation Choices Choosing a Graphical or Command-line Installation Choosing a Media or Network Installation Chapter 3: Installing Envinsa Using the Envinsa Installer Using the Command-line Installer Chapter 4: Postinstallation Tasks Setting up JDBC Drivers Configuring WebSphere Servers Installing XML Processing Files Configuring Envinsa Services Gateway Service Presentation Service Profile Management Service

4 Appendix A: Running the Envinsa Demo Application Starting the Envinsa Demo Application Using the Envinsa Demo Application Appendix B: Configuring an iplanet Directory Server Appendix C: Troubleshooting Installation Problems Envinsa Log Files Error Messages Message: "Error: Can t open display:" One of the Installation Directories Is Not Valid Message: "112: Internal Error in Windows Installer" Envinsa 4.1

5 Requirements 1 This chapter discusses the additional Envinsa documentation you must read and the hardware and software configurations you can use with Envinsa. In this section: Release Notes and Envinsa Documentation System Requirements Supported Software

6 System Requirements Release Notes and Envinsa Documentation Before installing Envinsa, you must read the Envinsa Release Notes. These notes are the most recent source of information you need to know to install and use Envinsa, including known issues. The Release Notes are in the Envinsa Documentation Library on reference.mapinfo.com. You should also read the Envinsa Product Guide for more information about the services, dependencies, and deployment strategies. The Envinsa Install Guide only contains information that relates to the installation procedure. The Envinsa Documentation Library contains the latest versions of all Envinsa guides in PDF and HTML formats. You can view the documents individually or download the entire library to your computer as a ZIP file. The guides in the library are updated as needed. System Requirements The following table summarizes the Envinsa hardware and software requirements. Envinsa Requirements Category Disk Space Requirement A complete Envinsa installation requires 1 GB for Envinsa services and tools plus additional space for data components. The space required for data components depends on the geography of the data. For example: Data for North America requires approximately 30 GB. Data for large European countries requires between 5 and 15 GB. Data for most other countries requires less than 5 GB. Depending on the components you choose to install, your installation may require less than these amounts. Memory A complete Envinsa installation requires 4 GB of memory. Depending on the components you choose to install, your installation may require less than this amount. As a guideline, the Routing, Presentation, and Location Utility services each require 1 GB of memory. The other services and components require 1 GB of memory in total. Operating Systems Any 32-bit version of: Application Servers IBM WebSphere Windows Server 2003 Standard Edition Solaris 10 for SPARC IBM AIX 5.3 Red Hat Enterprise Linux AS 3 for x86 Red Hat Enterprise Linux AS 3 Update 1 for x86 6 Envinsa 4.1

7 Chapter 1: Requirements Envinsa Requirements(continued) Category Java Virtual Machine Directory Servers Requirement WebSphere has its own instance of the IBM JVM. You must use this JVM with Envinsa. To use the Profile Management Service you must have an LDAP v3 compatible directory server. Envinsa was validated with iplanet 5.1. Supported Software Envinsa also supports the use of the following software: Supported Software Security Category Supported Software By default, Envinsa services are installed with: Apache XML Security (Signature implementation only) Bouncy Castle JCE for JDK 1.4 Envinsa services also support the following security related tools: XML Encryption and Signature IBM XML Security Suite Verisign Trust Service Integration Kit (TSIK) Java Cryptography Extension (JCE) IBM Security Extension (available from the IBM JRE) Sun JCE (available from the Sun JDK) Bouncy Castle JCE for JDK 1.5 (bcprov-jdk jar) Databases Envinsa supports the following databases: MapInfo Tables IBM DB2 8.1 (non-spatial) Microsoft SQL Server 2000 Service Pack 3 with MapInfo SpatialWare 4.8 Microsoft SQL Server 2005 MYSQL 4.1 Oracle9i Database Release 2 with Oracle Spatial and Oracle Locator Oracle Database 10g with Oracle Spatial and Oracle Locator Envinsa only supports case-insensitive databases. For more information on configuring your database to support this requirement, see your database documentation. Install Guide For Websphere Application Servers 7

8 Supported Software Supported Software (continued) Category SNMP Agents Java Management Extensions (JMX) Web Browsers Envinsa supports any SNMP agent. Envinsa is validated against Java Dynamic Management Kit (JDMK) 5.0. Envinsa supports JMX agents that monitor service activities through a JMX server. Any of: Supported Software Microsoft Internet Explorer 6.0 Mozilla Firefox Envinsa 4.1

9 Preinstallation Tasks 2 This chapter describes the tasks you must perform before installing Envinsa. Note: This chapter uses forward slashes to separate directories in paths that apply to all operating systems. Windows users must use backslashes when specifying paths. In this section: Install Application Server Instances Tasks Recommendations Decide on Installation Choices

10 Tasks Install Application Server Instances This guide describes the tasks you must perform to install the Envinsa services on your application server. To avoid any conflicts between the Envinsa services and your existing web applications, you should install one or more separate instances of your application server exclusively for Envinsa. This allows you to make configuration changes to your Envinsa services and applications without affecting any other applications. Tasks Before installing Envinsa, you must perform the following tasks: Set Default JVM Heap Sizes Remove Conflicting jdom.jar File Create a Directory for Installer Log Files Start Application Server Instances Set Default JVM Heap Sizes The Java Virtual Machine (JVM) uses multiple predefined memory spaces for various types of memory management. The two main spaces are heap for object instances and permanent generation (PermSize) for code and static data. You must set the default size for each of these spaces to optimize the performance of Envinsa services. For most installations, MapInfo recommends that you configure each application server instance to use 1024 MB of heap space. Consider the following guidelines when determining the size for each space: Route Service Heap size requirements are affected by the data used (it varies by country), the number and complexity of requests, and the type of result (with map or without). Memory usage is determined for one service instance per country for performance reasons. Presentation Service Memory usage depends on the mapping data used (it varies per country) and layer search requirements. Location Utility and Position Refine Services Memory usage varies according to the complexity of queries and the number of candidate matches. All other Envinsa Services Memory usage varies according to the complexity of queries and the number of candidate matches, but these services are not memory intensive. Batch Geocoding Memory usage varies according to the size of the dataset. You may need to increase the JVM heap size to accommodate large datasets. For example, if you know you will be doing memory-intensive Route service processing, you may want to allocate a maximum heap size of 2048 MB. However, do not allocate a total heap size that exceeds your available memory because service requests will run out of memory and fail. 10 Envinsa 4.1

11 Chapter 2: Preinstallation Tasks To set the recommended values: 1. Start and log on to the WebSphere administrator console. The default URL is 2. Expand the Servers item on the left hand pane and select the server hosting your Envinsa Services. 3. Scroll down the Additional Properties menu under the Application Server page and select Process Definition. 4. Scroll down the Additional Properties menu under the Process Definition page and select Java Virtual Machine. 5. On the Java Virtual Machine page, set the Maximum Heap Size property to After completing these steps, apply and save all changes. Then restart the server in order for changes to take effect. Remove Conflicting jdom.jar File WebSphere 6.0 includes JDOM 1.0b7 in <Websphere_home>/lib. This version causes a conflict with JDOM 1.0b9, which is included with Envinsa. If you are using WebSphere 6.0, then you must delete <WebSphere_home>/lib/jdom.jar and restart WebSphere before you can install Envinsa. If you have concerns about how this will affect your existing applications, then contact MapInfo Technical Support. Create a Directory for Installer Log Files Note: This section only applies to Windows users. The Envinsa installer creates log files in C:\TMP and the directory specified with the %TEMP% environment variable. You must create both directories, if they do not exist, before starting the installer. Start Application Server Instances Your application server and all instances you will use for Envinsa must be installed and running before you start the Envinsa installer. If they are not currently running, then start them now. Recommendations The following recommendations provide additional information that can help you install Envinsa in a way that best uses your system resources. The recommendations are organized by: Services Data Components Install Guide For Websphere Application Servers 11

12 Recommendations Services The following recommendations apply to all Envinsa services. Optimizing Application Server Performance The Presentation, Route, and Location Utility services individually have large memory requirements. To ensure the best performance for these services, MapInfo recommends that you install each of these services into a separate application server instance within the same WebSphere node. During the installation process, the installer will give you the opportunity to install each service into a separate application server instance. To help you during the installation process, consider creating a work sheet similar to the following example: Decide which services you will install and write the name of each service under one instance on the work sheet. When the installer prompts you to select the services you want to install under each application server instance, you can refer to the work sheet as a reference. Using a Naming Convention for Multiple Installations MapInfo recommends that you use a naming convention for your installation. This naming convention will help you to keep track of the components that you have installed or upgraded when looking at the file system. This is especially useful if you are installing multiple application server instances. One way to keep track of multiple instances is to use a naming convention based on the port number of the instance, such as Envinsa/domain7070 and Envinsa/domain7080. A sample naming convention would be: Domain/Envinsa<version>/instance<version><port> Increasing the File Descriptor Limit Note: This recommendation only applies to Solaris installations. The file descriptor limit in Solaris determines the number of open file handles any single process can hold. For Envinsa installations, we recommend that you set the file descriptor limit to its maximum value before starting each application server instance. To do this, enter the following command that matches your shell environment: > ulimit -n 1024 (Bourne or Korn Shell) > unlimit descriptors (C Shell) We also recommend that you make this a permanent change to your application server startup scripts and batch files. This ensures that your application server will always have sufficient file descriptors. 12 Envinsa 4.1

13 Chapter 2: Preinstallation Tasks Data Components The following recommendations apply to all Envinsa data components. Optimizing Disk Space for Data Components If you are installing multiple instances of Envinsa services on this computer, then you should only install the data components once. In the second installation, choose to reuse existing data and then select the data domain from the first installation. Installing Data for Multiple Countries By default, data is installed under the <Envinsa_home>/<Envinsa_version>/DataDomain directory. If you want to install data for multiple countries to the same domain location, then plan the directory structure that you want to install to at this location. For example, plan to use country-specific subdirectories under the data directory, so that it would have the following structure for Australia (AU), Germany (DE), and United Kingdom (UK) data: MapInfo/ Envinsa-4.1/ DataDomain/ AU/ DE/ UK/ Supporting Multi-Country Routing Requests The Envinsa Route Service can generate routes that involve multiple countries. To use this feature, you must install the data for each country under the same data domain. For example, to create a route from France to Spain, you must install the data for both countries in the same directory. Decide on Installation Choices Before starting the Envinsa installer, you must decide on the following choices: Choosing a Graphical or Command-line Installation Choosing a Media or Network Installation Choosing a Graphical or Command-line Installation You can install Envinsa using either a graphical or command-line installer. The graphical installer guides you through the installation process by asking a series of questions. This is the installer that most users will use to install Envinsa. The command-line installer allows you to install Envinsa from the command prompt or scripts. The command-line installer requires you to specify your installation preferences in a configuration file before running the installer. MapInfo expects only advanced users whose environments require a command-line installer to use this method. Install Guide For Websphere Application Servers 13

14 Decide on Installation Choices Choosing a Media or Network Installation You can install Envinsa either from the product DVDs or from your hard drive. Installing from DVDs is called a media installation by the Envinsa installer. If you select this option, then the installer will prompt you to change disks during the installation process. If you prefer, then you can copy all of the Envinsa DVDs to your hard drive or a shared network drive. This is called a network installation by the Envinsa installer. Performing a network installation can simplify the installation process because you will not need to change disks after the installer starts. However, you must ensure that you have enough free disk space on the computer after copying the disks to install Envinsa. Note: If you are using the command-line installer, then you must perform a network installation. To prepare for a media installation: If you are installing Envinsa on a UNIX or Linux computer, then note the following considerations: Run the installer from the DVD by starting it from your user directory or the root directory. This ensures that you will be able to eject the DVD to insert the next disk during the installation process. On Solaris computers, always use the /cdrom/cdrom0 directory when referring to the DVD-ROM drive. A disk label directory may be available, but do not use it. To prepare for a network installation: 1. Create a directory that will hold the contents of the Envinsa DVDs. 2. Copy the contents of each DVD disk to that directory. You must copy every disk excluding the license and documentation disks. 3. If you copied the DVDs to a computer that is not the computer where you are installing Envinsa, then you must ensure the directory where you copied the files is accessible to the computer where you are installing Envinsa. If you are installing Envinsa on a UNIX or Linux computer, then mount the copied directory on the machine where you are installing Envinsa. If you are installing Envinsa on a Windows computer, then map the copied directory to a drive on the computer where you are installing Envinsa. After you finish copying the directories, you will have a directory structure similar to the following: ENVINSA_DVDS ENV41DAT1_US_CA... ENV41DEMO ENV41SRV6 InstData This example shows the directory structure for the United States and Canada Envinsa media. All of the media directories are under the ENVINSA_DVDS directory, which was created in step Envinsa 4.1

15 Installing Envinsa 3 This chapter guides you through the process of installing Envinsa. You must complete all applicable tasks in Preinstallation Tasks in Chapter 2 on page 9 before continuing with this chapter. In this section: Note: Only follow the instructions in one of the following sections. See Choosing a Graphical or Command-line Installation on page 13 for more information on the two installers. Using the Envinsa Installer Using the Command-line Installer

16 Using the Envinsa Installer This section guides you through the process of starting the Envinsa installer. To install Envinsa using the Envinsa installer: 1. Start the Envinsa installer by running one of the following commands: (UNIX or Linux) sh <source>/startinstall.sh (Windows) <source>\setup.exe Note: If you are running the installer from disk on a UNIX or Linux system, then enter the preceding command from the root directory or your home directory. Running the command from the directory where the disk is mounted can prevent you from ejecting the disk during the installation process. If you copied the Envinsa Install Disk DVD to your computer or a network drive, then <source> is the directory where you copied the DVD to. If you are running the installer from the DVD directly, then <source> is the DVD drive. This starts the Envinsa installer. While running the installer, you can click Help for more information on the current screen. 2. In the Introduction screen, review the introduction and click Next. 16 Envinsa 4.1

17 Chapter 3: Installing Envinsa 3. In the License Agreement screen, review the agreement. If you agree with the agreement, then select I accept... and click Next to continue with the installation. Otherwise, select I do NOT accept... and click Cancel to exit the installer. 4. In the What s New screen, review the new features and click Next. Install Guide For Websphere Application Servers 17

18 5. In the Enter Serial Number screen, enter your Envinsa serial number and click Next. The serial number is located on the outside of your Envinsa product box. 6. In the Choose the Envinsa Package Directory screen, click Choose... and select the directory that contains Envinsa.xml on your computer. After selecting the directory, click Next. Note: After clicking Next, you cannot return to this screen and select a different package directory. If you chose the wrong directory, then you must quit the installer and start it again. The Envinsa.xml file is included on the Envinsa License Disk or provided to you by your Envinsa representative. If you have saved the file on your computer, then specify the directory where you saved the file. Otherwise, insert the license disk and specify that directory. 18 Envinsa 4.1

19 Chapter 3: Installing Envinsa 7. In the Enter User Name and Password screen, enter the user name and password for the Envinsa administrator account. The user name and password are both case sensitive and can only contain letters, numbers, and periods. The installer will create this account, which you use to access the Envinsa administrative tools such as Enterprise Manager and Content Manager. If you have previously installed Envinsa on this computer, then you must enter information for an existing administrator account. 8. In the Use Existing Data or Install New Data screen, specify if you want to install new data or not and click Next. Install Guide For Websphere Application Servers 19

20 9. If you chose to install new data in the previous screen, then skip to step 10. In the Choose Existing Envinsa Data Domain Directory screen, specify the location of your existing Envinsa data and click Next. 10. In the Choose Install Directory screen, enter the directory where you want to install Envinsa and click Next. 20 Envinsa 4.1

21 Chapter 3: Installing Envinsa 11. If you chose to reuse existing data in step 8, then skip this step. In the Choose Data Domain Directory screen, enter the directory where you want to install Envinsa data and click Next. 12. In the Choose Install Set Type screen, select Custom and click Next. Install Guide For Websphere Application Servers 21

22 13. In the Choose Install Set screen, select the services and data components that you want to install and click Next. If there are any data components listed under a service, then you must select at least one of them to use the service. Note: If you select Find Location, then you must also select Directory. If you select Route, then you must also select Presentation and MapManager. If you select Presentation, then you must also select MapManager. 14. In the Select Web Application Server screen, select WebSphere 6.0 and click Next. 15. In the Select Service to Install in Server Instance screen, you must choose which services you want to install in this application server instance. If you are installing Envinsa into multiple 22 Envinsa 4.1

23 Chapter 3: Installing Envinsa instances, then see Optimizing Application Server Performance on page 12 for recommendations. Select the services you want to install to this application server instance and click Next. You can select multiple services by holding down the Control key while selecting each service. 16. In the Enter WebSphere Application Server Information screen, enter the configuration information for the application server instance and click Next. For more information on the fields in this screen, click Help. Install Guide For Websphere Application Servers 23

24 17. In the Install More Services screen, do the following: If you want to install Envinsa services into another application server instance, then select Yes and click Next. When you click Next, the installer will ask you to configure the next application server instance starting from step 14. If you have configured all of your application server instances for Envinsa, then select No and click Next. 18. In Choose Java Virtual Machine screen, select a JDK virtual machine from the list and click Next. The installer will configure the Envinsa tools, such as Enterprise Manager and Content Manager, to use this virtual machine. You must select a JDK and not a JRE virtual machine. 24 Envinsa 4.1

25 19. Depending on your operating system, you will see one of the following screens. Chapter 3: Installing Envinsa If you are using Windows, then in the Choose Shortcut Directory screen, select where you want to create Envinsa shortcuts and click Next. Click Help for more information on these choices. If you are using UNIX or Linux, then in the Choose Link Directory screen, select where you want to create Envinsa links and click Next. Click Help for more information on these choices. Install Guide For Websphere Application Servers 25

26 20. In the Select Network or Media Install screen: Select Network, if you copied the Envinsa DVDs to a directory on your computer. Select Media, if you did not copy the DVDs. For more information on this choice, see Choosing a Media or Network Installation on page 14. Click Next to continue. 26 Envinsa 4.1

27 Chapter 3: Installing Envinsa 21. Depending on your choice on the previous screen, you will see one of the following screens. If you chose to install from the network, then in the Specify the Network Location screen, click Choose and select the directory you copied the Envinsa DVDs to. Click Next to continue. If you chose to install from media, then in the Specify the Disk Drive screen, click Choose and select the drive you will use for the Envinsa DVDs. Click Next to continue. Install Guide For Websphere Application Servers 27

28 22. In the Pre-Installation Summary screen, review the installation options and click Install to start installing Envinsa. The installer will install Envinsa to your computer. If the installer prompts you to insert a data disk that you do not have, then the most likely cause is that you selected a data component that you are not licensed to use. To proceed with the installation, click Skip in the warning dialog. 28 Envinsa 4.1

29 Chapter 3: Installing Envinsa 23. After installing Envinsa, if you installed the Envinsa Demo application, the installer will ask you if you want to run the application. Select your choice and click Next. Note: Some Envinsa services and components require that you perform additional tasks before you can run them successfully. You may not be able to run all parts of the Demo application until you complete all of the tasks described in Chapter 4: Postinstallation Tasks. For information on running the demo application, see Appendix A: Running the Envinsa Demo Application. 24. In the Install Complete screen, click Done to exit the installer. This completes the Envinsa installation process, however, there are additional tasks you must perform to configure the installation. You must perform these tasks to successfully use Envinsa. For the remaining tasks, see Postinstallation Tasks on page 33. Install Guide For Websphere Application Servers 29

30 Using the Command-line Installer Using the Command-line Installer This section guides you through installing Envinsa using the command-line installer. To do this: 1. Open or change to the following directory: <Envinsa_media>/InstData/<os>/VM where <Envinsa_media> is the directory where you copied the Envinsa DVDs to and <os> represents your operating system. For more information on this task, see Choosing a Graphical or Command-line Installation on page Copy one of the following files to the directory you opened in step 1. If you are installing data for the United States and Canada (US_CA), then copy <Envinsa_media>/InstData/Templates/silentinstall_US_CA.properties. If you are installing data for any single country, then copy <Envinsa_media>/InstData/ Templates/silentinstall_GENERIC.properties. 3. Rename the file you copied to installer.properties. You now have the following file: <Envinsa_media>/InstData/<os>/VM/installer.properties 4. Change the permissions for the file to ensure you can save changes you make to it. 5. Open installer.properties in a text editor. 6. If you are using the single country properties file, then replace all occurrences of {ISOCC2} in the file with the two letter country code for the data you are installing. For example, if you are installing Envinsa with data for Germany, then replace {ISOCC2} with DE. 7. Specify values for the parameters in the file. See the comments in the file for more information about each parameter. 8. Depending on your operating system, perform the following tasks from the same directory as the properties file. If you are using UNIX or Linux, then do the following: a. Run sh install.bin. This immediately returns you to a command prompt. b. Monitor /tmp/envinsa_errors.log. This file is updated as the installer installs each component. The installation is complete after the following line appears in the file: calling cleanupunix() If you are using Windows, then do the following: a. Run install.exe. This immediately returns you to a command prompt. b. Monitor C:\TMP\envinsa_errors.log. This file is updated as the installer installs each component. The installation is complete after the following line appears in the file: calling CleanUpWin32() 9. Rename installer.properties. If you do not rename or move this file, then the next time you try to start the installer from this directory, it will automatically use the values set in this file. Renaming this file prevents you or other users from accidentally reinstalling Envinsa. 30 Envinsa 4.1

31 Chapter 3: Installing Envinsa This completes the Envinsa installation process, however, there are additional tasks you must perform to configure the installation. You must perform these tasks to successfully use Envinsa. For the remaining tasks, see Postinstallation Tasks on page 33. Install Guide For Websphere Application Servers 31

32 Using the Command-line Installer 32 Envinsa 4.1

33 Postinstallation Tasks 4 This chapter describes the steps you must perform after running the Envinsa installer. Note: This chapter uses forward slashes to separate directories in paths that apply to all operating systems. Windows users must use backslashes when specifying paths. In this section: Setting up JDBC Drivers Configuring WebSphere Servers Configuring Envinsa Services

34 Configuring WebSphere Servers Setting up JDBC Drivers The following services or components require database connections using JDBC: Content Manager Directory Service Map Manager Presentation Service Web Feature Service To install the JDBC drivers for these services and components, do the following: 1. Obtain copies of the JDBC driver JAR files for your database. For IBM DB2, use the DB2 Universal JDBC Driver provided with DB2. For Microsoft SQL Server, download the JDBC drivers for your database from msdn.microsoft.com. For Oracle Spatial, download the ojdbc14.jar JDBC driver from otn.oracle.com. 2. Copy the driver files to <WebSphere_home>/AppServer/<profile>/installedApps/ <cell_name>/<service>.ear/<service>.war/web-inf/lib directory, where <WhereSphere_home> is your WebSphere installation directory, <profile> and <cell_name> correspond to the WebSphere instance, and <service> is the name of the service you want to use the JDBC driver with. Repeat this for each of the services in the above list that you are using. As an example, for the Directory Service on Windows, copy the driver files to C:\WebSphere\ AppServer\myProfile\installedApps\myCell\Envinsa\Directory.ear\ Directory.war\WEB-INF\lib. 3. If you installed Content Manager, then copy the driver files to <Envinsa_home>/ Envinsa-4.1/PlatformDomain/CMC/lib, where <Envinsa_home> is the directory where you installed Envinsa. 4. If you installed Map Manager, then copy the driver files to <Envinsa_home>/Envinsa-4.1/ PlatformDomain/MapManager/lib, where <Envinsa_home> is the directory where you installed Envinsa. This change will take effect the next time you start the application server instances. After configuring the JDBC driver, you must create data sources for each of the services and components described at the beginning of this section. See each service s Reference Guide for more information on doing this. For more information about installing the JDBC drivers, see the documentation for your database and application server. Configuring WebSphere Servers WebSphere users must complete the following task before using Envinsa: Installing XML Processing Files Complete all of the tasks in this section and then restart your application server instances so the changes can take effect. 34 Envinsa 4.1

35 Chapter 4: Postinstallation Tasks Installing XML Processing Files WebSphere includes some library files for XML processing. These files conflict with the comparable Envinsa files. You must resolve this conflict if you installed any of the following services: Directory service Find Location service Location Utility service Presentation service Route service To resolve the conflict, you must install additional XML processing files. To do this: 1. Shut down the WebSphere servers with Envinsa applications. 2. Create a directory named endorsed under <WebSphere_home>/AppServer/java/jre/ lib, where <WebSphere_home> is the directory where your WebSphere instance was installed. 3. Copy the following files from the <WebSphere_home>/.../WEB-INF/lib directory for any Envinsa service into the endorsed directory: jdom.jar xalan.jar xercesimpl.jar xml-apis.jar xmlparserapis.jar For example, copy C:\WebSphere\myProfile\AppServer\installedApps\myHost\ Directory.ear\Directory.war\WEB-INF\lib\jdom.jar to C:\WebSphere\ AppServer\java\jre\lib\endorsed. 4. Create a file named <WebSphere_home>/AppServer/java/jre/lib/jaxp.properties and add the following lines to the file: javax.xml.transform.transformerfactory=org.apache.xalan.processor.transformerfactoryimpl javax.xml.xpath.xpathfactory=org.apache.xpath.jaxp.xpathfactoryimpl javax.xml.parsers.saxparserfactory=org.apache.xerces.jaxp.saxparserfactoryimpl javax.xml.parsers.documentbuilderfactory=org.apache.xerces.jaxp.documentbuilderfactoryimpl If jaxp.properties already exists in this directory, then add the lines to the existing file. 5. Restart the WebSphere servers you stopped in the first step. Configuring Envinsa Services This section describes additional tasks you must perform for specific services. Complete the following sections for the services you have installed: Gateway Service Presentation Service Profile Management Service Install Guide For Websphere Application Servers 35

36 Configuring Envinsa Services Gateway Service Note: This section only applies if you want to use the Ericsson Emulator with the Gateway Service. The Ericsson emulator requires the Java Secure Socket Extension (JSSE) classes. These classes are not included with the IBM WebSphere JDK. To use these classes: 1. Download and install JSSE from 2. Copy jsse.jar to <WebSphere_home>/AppServer/<profile>/installedApps/ <cell_name>/gateway.ear/gateway.war/web-inf/lib directory, where <WhereSphere_home> is your WebSphere installation directory, and <profile> and <cell_name> correspond to this WebSphere instance. This change will take effect the next time you start the application server instances. Presentation Service If you have installed the Presentation service, then perform the following tasks: Enabling Native Acceleration Method Configuring the Virtual Frame Buffer (Solaris only) Enabling Native Acceleration Method The Presentation Service works with the Java Advanced Imaging (JAI) API. When you install the Presentation service, the installer also installs platform-specific library files for JAI 1.1.2, which are optimized for your operating system. To ensure the best performance for the Presentation service, add the correct JAI native library to your environment variables. To do this: 1. Add <Envinsa_home>/PlatformDomain/Presentation/JAI/native/tools/<os> to your PATH environment variable, where <Envinsa_home> is the directory where you installed Envinsa and <os> is either linux, solaris, or win, depending on your operating system. 2. If you are using a UNIX or Linux operating system, then add <Envinsa_home>/ PlatformDomain/Presentation/JAI/native/tools/<os> to your LD_LIBRARY_PATH environment variable, where <Envinsa_home> is the directory where you installed Envinsa and <os> is either linux or solaris, depending on your operating system. This change will take effect the next time you start the application server instances. For more information about JAI refer to the Sun Web site at java-media/jai/. Configuring the Virtual Frame Buffer Note: This section only applies to Solaris installations using a virtual frame buffer. If you are using the Presentation service on a Solaris system and using a virtual frame buffer, then you must add the following parameter to the _JAVA_OPTIONS environment variable: -Dsun.java2d.pmoffscreen=false This change ensures that your computer can render theme legends. For more information on the pmoffscreen parameter, see the Java documentation. 36 Envinsa 4.1

37 Chapter 4: Postinstallation Tasks This change will take effect the next time you start the application server instances. Profile Management Service The Profile Management service requires a running LDAP directory server. Before using the Profile Management service, you must install and configure an LDAP schema for your directory server. To do this: 1. Install the Envinsa LDAP Schema 2. Configure the Directory Server 3. Register the Directory Server with Envinsa Install the Envinsa LDAP Schema To install the schema: 1. Open or change to the <Envinsa_home>/PlatformDomain/Profile/scripts directory, where <Envinsa_home> is the directory where you installed Envinsa. 2. Open one of the following scripts in a text editor. If you are using Windows, then open create_ldap_schema.bat. If you are using UNIX or Linux, then open create_ldap_schema.sh. 3. In the text editor, modify the following parameters with values that correspond to your LDAP server: LDAP_URL="ldap://miaware.mapinfo.com:389" LDAP_USER="cn=Directory Manager" LDAP_PASSWD="mypassword" 4. Save your changes to the script. 5. Run the script. The script will run and install the Envinsa LDAP schema to your directory. Continue configuring the Profile Management service with Configure the Directory Server below. Configure the Directory Server The following steps describe the general steps you must perform to configure your directory server for the Profile Management service. If you are using an iplanet Directory Server, then see Configuring an iplanet Directory Server in Appendix B on page 43. Otherwise, see your directory server documentation for more information on completing these steps. 1. On the directory server, create a new root suffix named o=miaware.com and an associated database. 2. If you are using UNIX, then convert the line endings for <Envinsa_home>/PlatformDomain/ Profile/SampleProfileData/miaware.com.ldif using dos2unix or a similar command. <Envinsa_home> is the directory where you installed Envinsa. Install Guide For Websphere Application Servers 37

38 Configuring Envinsa Services 3. Initialize the database you created for the root suffix and populate it with the sample data from <Envinsa_home>/PlatformDomain/Profile/SampleProfileData/ miaware.com.ldif, where <Envinsa_home> is the directory where you installed Envinsa. This file contains sample data for the Envinsa Demo application. You now have a directory with sample data for the Envinsa Demo application. You can also use this sample data as a template for your profile data. Continue configuring the Profile Management service with Register the Directory Server with Envinsa below. Register the Directory Server with Envinsa To register your directory server with Envinsa, you must perform the following tasks: 1. Start Envinsa Enterprise Manager by running either of the following commands: If you are using Windows, then run <Envinsa_home>\Tools\EnterpriseManager\ EnterpriseManager.bat. Otherwise, run <Envinsa_home>/Tools/EnterpriseManager/EnterpriseManager.sh. 2. Log into Enterprise Manager using the Envinsa administrator account you created during the installation process. 3. In the Enterprise Manager menu, select Tools > Views > Advanced. This ensures you can see all administration options in the menus. 4. In the list of services and Envinsa components, select the Profile service. 5. In the menu, select View > Services > Registration > Parameter Settings. This displays the Parameter Settings tab for the service. 6. Under the tab, expand all options under ProfileService and select Properties. This displays the Profile Management service properties. 7. Double-click on each of the following parameters and set them to the appropriate values for your directory server. These must match the values you specified in Install the Envinsa LDAP Schema on page 37. Enterprise Identifier: Enter miaware.com. This value must match an Envinsa root suffix. LDAP Server URL LDAP Administrator Identifier LDAP Administrator Password 8. Click the Save icon ( ) to save your changes. This completes all of the tasks you must perform to configure the Profile Management service. 38 Envinsa 4.1

39 Running the Envinsa Demo Application A The Envinsa Demo Application allows you to test your Envinsa installation and use the services. In this section: Starting the Envinsa Demo Application Using the Envinsa Demo Application

40 Using the Envinsa Demo Application Starting the Envinsa Demo Application To start the Envinsa Demo Application, you must: 1. Start the application server instances that you configured for Envinsa services. 2. Open in a web browser, where <hostname> is the name of your computer, <port> is the port number for the instance where you installed the Envinsa Demo Application. You can see the name and port numbers for the application by opening <Envinsa_home>/Envinsa-4.1/Logs/envinsa_installer_log_<time>.htm, where <Envinsa_home> is the directory where you installed Envinsa, and <time> is the approximate time when you installed Envinsa. This file lists information about your Envinsa installation. 3. Log in to the application. The default user name is demo and the default password is demo. After logging in, you will see the main page for the demo application. Using the Envinsa Demo Application The Envinsa Demo Application has samples that demonstrate how many of the Envinsa services work. For each sample, you can see a simple HTML form where you can enter your request information or the corresponding XML text that is sent to the web service. When you submit a request, the application forwards it to the Envinsa service, and then displays the resulting XML text in the browser. For Presentation Service requests, you also have the option of displaying the map as a graphic. The following example explains how you can use the application create a map with the Presentation Service. To do this: 1. Log in to the Envinsa Demo Application. For information on this task, see Starting the Envinsa Demo Application on page On the left side of the browser window, under Service Demo, select HTML. This displays HTML forms instead of XML text on the right side of the window. 3. On the left side of the window, select Presentation. This displays Envinsa Presentation Web Service on the right side of the window. 4. From the drop down list, select AnalysisLayer. This shows the AnalysisLayer sample form. 40 Envinsa 4.1

41 Appendix A: Running the Envinsa Demo Application 5. Click Submit Request to submit the default form information. This opens a new browser window with a world map showing the relative population of each country and how each population is distributed by age groups. Generating this map was one sample in the demo application. You can continue using the demo application by submitting requests for different samples and services. Install Guide For Websphere Application Servers 41

42 Using the Envinsa Demo Application 42 Envinsa 4.1

43 Configuring an iplanet Directory Server B This appendix provides detailed instructions on configuring the iplanet Directory Server for the Envinsa Profile Management service. These steps are described for any directory server in Install the Envinsa LDAP Schema on page 37. The following steps assume that you have already installed the Envinsa LDAP schema to your directory server and only describe the iplanet-specific tasks you must perform. To configure an iplanet directory server for the Profile Management service: 1. Start the iplanet Console and log in as cn=directory Manager. You must specify the directory manager password for this account. 2. In the console, expand the list of servers until you see Directory Server. 3. Double-click Directory Server to open it. This opens another console window showing a list of tasks you can perform for this server. 4. Select the Configuration tab and select Data in the navigation tree.

44 5. Right-click on Data and select New Root Suffix from the menu that appears. This opens the Create new root suffix dialog. 6. Complete the dialog as follows: a. In the New suffix field, enter o=miaware.com. b. Check the Create associated database... check box. c. In the Database name field, enter a name for the database. d. Click OK to create the root suffix. 7. Under the Configuration tab, expand Data to show the o=miaware.com root suffix. Expand the suffix and select the database you created. 8. Initialize the database as follows: a. Right-click on the database and select Initialize Database from the menu that appears. This opens a dialog asking you for an LDIF file. b. If you are using UNIX, then convert the line endings for <Envinsa_home>/ PlatformDomain/Profile/SampleProfileData/miaware.com.ldif using dos2unix or a similar command. <Envinsa_home> is the directory where you installed Envinsa. c. In the dialog, enter <Envinsa_home>/PlatformDomain/Profile/ SampleProfileData/miaware.com.ldif, where <Envinsa_home> is the directory where you installed Envinsa. This file contains sample data for the Envinsa Demo application. d. Click OK and then Yes to initialize the database. This opens a dialog showing the status of the initialization. e. When Import Finished appears on the dialog, click Close. This completes the iplanet-specific tasks you must perform to use the Profile Management service. Before using the service, you must register it with Envinsa. For more information, see Register the Directory Server with Envinsa on page Envinsa 4.1

45 Troubleshooting Installation Problems C This appendix provides additional information to help you identify and resolve errors that occur during installation. In this section: Envinsa Log Files Error Messages