Installation Guide Provided by DataSplice, LLC Phone: 1.800.377.1974 ext. 1732 (toll-free) Phone: 1.970.232.1732 (sales) Email: datasplice@datasplice.com The information contained in this document is intended to describe the DataSplice Mobility Suite. This information is subject to change at any time, without notice. We would be pleased to provide a quote or a proposal to address specific project needs, upon request. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 1 SECTION A. MAXIMO PLUG-IN ARCHITECTURE ................................................................................................. 4 SECTION B. SYSTEM REQUIREMENTS ................................................................................................................ 5 SECTION C. VERIFICATION OF REQUIREMENTS ................................................................................................. 6 SECTION D. DATASPLICE INSTALLATION STEPS ................................................................................................. 7 SECTION E. DATASPLICE LICENSE INSTALLATION .............................................................................................. 8 SECTION F. CONFIGURING DATASPLICE5.0 ..................................................................................................... 13 F.1 F.2 F.3 F.4 CONFIGURING THE ADO.NET DATA SOURCE ..........................................................................................................13 CONFIGURE THE MAXIMO PLUGIN .........................................................................................................................14 LOADING THE OUT OF THE BOX CONFIGURATION FILES ..............................................................................................16 INITIAL SECURITY CONFIGURATION.........................................................................................................................17 SECTION G. TESTING THE APPLICATION INSTALLATION .................................................................................. 17 SECTION H. LDAP CONFIGURATION ................................................................................................................ 19 SECTION I. DESKTOP CLIENT INSTALLATION .................................................................................................. 19 SECTION J. HANDHELD DEVICE INSTALLATION ............................................................................................... 20 SECTION K. TROUBLE SHOOTING .................................................................................................................... 21 K.1 CONNECTION TROUBLESHOOTING .........................................................................................................................21 DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 2 TRADEMARKS DataSplice® and InspecTMI® are registered trademarks of DataSplice, LLC. Maximo® and Maximo Everyplace® is a registered trademark of the IBM Corporation in the United States and other countries. DataSplice is an IBM Advanced Business Partner. IBM is not responsible for the content or accuracy of this information or for the content, performance or quality of DataSplice products or services. Microsoft®, Visual Studio®, Windows®, and the Windows logo are either registered trademarks or trademarks of Microsoft Corporation in the United States and other countries. Other names and products mentioned herein may be the trademarks or registered trademarks of their respective owners. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 3 Section A. Maximo Plug-in Architecture The following diagram demonstrates how DataSplice integrates with a Maximo application server for mobile access: Note that only the server communicates with Maximo, the clients do not directly access any of the Maximo components Data queries use a native database connection for performance reasons and are processed by the same database user All transactions to modify data are committed through the Maximo Business Object (MBO) layer, which ensures that user permissions, customizations, etc. are respected DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 4 Section B. System Requirements Requirements Administration Client DataSplice Server Remote Client on Win32 PC Remote Client on Mobile Device Microsoft or later Microsoft Microsoft Microsoft Microsoft 1 GHz or faster 512 MB RAM (1 GB or more) Supported Operating Systems Processor Requirements Memory Requirements Windows XP (Home or Professional) service pack 2 Windows Windows Windows Windows Server 2003 family Vista Server 2008 family 7 500 MHz (1 GHz or faster recommended) 256 MB RAM (512 MB or more) Available Storage Requirements 250 MB (1 GB or more) 36 MB 48 MB (including Windows CE component files) Pocket PC (2003/Windows Mobile, Windows Mobile 5.0 and newer) Handheld PC running Windows CE.NET 5.0 or newer 300 MHz (400 MHz or faster) 32 MB ROM (64 MB or more) 64 MB RAM (128 MB or more) 32 MB or greater (including SQL CE data engine ;nonvolatile storage media recommended) Microsoft ActiveSync version 4.2 or newer if manually installing the DataSplice Remote Client on mobile devices Microsoft .NET Compact Framework version 3.5 or newer SQL Server CE Data Engine version 3.0 or newer (included with DataSplice Windows CE component files) Microsoft .NET Additional Required Components Supported Networks Framework versio n 3.5 Oracle ODP.NET provider 10.2 for Oracle 8.1.7 (32-bit support only) only required if Maximo database is Oracle Oracle ODP.NET provider 11.1 for Oracle 9, 10 and 11 -only required if Maximo database is Oracle Java Runtime Environment 1.6 or 1.7 Microsoft .NET Framework vers ion 3.5 SQLite is built in to the Win 32 desktop Remote Client for offline work. Microsoft .NET Frameworkversi on 3.5 Microsoft Internet Explorerversion 6 service pack 1 or newer SQL Server 2005 Express Edition Can also be used. TCP/IP networks (Ethernet, 802.11x, CDPD, etc.) ActiveSync connection (USB, serial, etc.) Access to port 4100 (or other port if altered from default configuration) DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 5 Section C. Verification of Requirements Before starting the installation of DataSplice verify that the server where you will be installing the application has the following installed: 1. Java 1.6 or 1.7- 32 bit: a. In the case the installation is on a 64 bit OS server, you still have to install the 32 bit version of the Java Runtime Environment (JRE). 2. .NET - minimum 3.5: a. To verify the installation of .net and the versions perform the following steps: i. Open windows explorer and navigate to: C:\Windows\Microsoft.NET\Framework ii. There you will find a set of folders that are named based on the versions of .net installed. iii. If you are working on a 64 bit os the path will be: C:\Windows\Microsoft.NET\Framework64 3. SQL or Oracle Driver: a. If using SQL as the database the SQL driver is installed as part of the OS. b. If using Oracle as the database you will likely need to install the ODP.NET driver. The latest version of ODP.NET driver supports database versions 8.1.7 through 11g and is available for download from Oracle's website. 4. If the servers that DataSplice is being installed are in Workgroups instead of Networks the port should be open. 5. If the installation is being performed in a network, verify that the following ports are open in the firewall: a. On the Maximo server that DataSplice will connect to: i. 13400 and 1099 b. On the server where DataSplice will be installed: i. 4180 c. NOTE: These ports are 100% configurable the ones listed above are just the default ports. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 6 Section D. DataSplice Installation Steps 1. Create a folder on the target server called DataSplice5.0, this folder can be crated on the primary drive or any other drive. 2. Copy the .zip files DS-5.0.X and DSMaximoPlugin-4.2.X to the target server. a. The DS-5.0.X file contains all of the application files including the server and client components. b. DSMaximoPlugin-4.2.X contains all of the files required by DataSplice to “talk” to Maximo. 3. Extract the DS-5.0.X.zip file into the DataSplice 5.0 folder. 4. Extract DSMAXIMOPlugin-4.2.X into the DataSplice 5.0 folder. All of the required files to continue the installation are now loaded in the server. 5. Now we need to create the DSSplicer.exe.config file. To do this perform the steps shown below: a. Using Windows explorer navigate to: <Installation_Drive>:\DataSplice5.0\Server\Resources\Scripts b. Double click on post_install_setup.bat: c. 6. This will create the necessary files and display the command window shown below. Press any key to close this window once the process is complete. Edit the DSSplicer.exe.config file: a. Navigate to: <Installation_Drive>:\DataSplice5.0\Server b. Right Click on the DSSplicer.exe.config file. c. Select the ‘Open With’ option. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 7 d. In the popup window select Notepad. e. Change “<add key="ServerInstanceName" value="DEFAULT" />” to “<add key="ServerInstanceName" value="ds_server_name" />”. In this example (“ <add key="ServerInstanceName" value="DSSTAGE" />”. ) 7. This will listen on port 4180. You can create multiple instance on a single server but each instance must listen on a separate port (ex – 4180 and 4181). f. Save and close the file. Installing the DataSplice Service: a. Open up a command prompt as an Administrator. b. Navigate to: <Installation_Drive>:\DataSplice5.0\Server c. Type the following: Dsservice.exe –install ‘ds_server_name’ i. Where ‘ds_server_name’ is the server name used in step 6 (It has to match 100% to the value in step 6). ii. In this Example DSSTAGE: iii. After installing the service exit the command prompt. 8. This completes the installation of DataSplice. Section E. DataSplice License Installation 1. Start the service. a. This service will be set to Automatic after when the configuration is complete. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 8 2. Run the administration Client a. Navigate to: <Installation_Drive>:\DataSplice5.0\Clients\Desktop b. Double click on the DSAdmin.exe application. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 9 3. Logging in to the DataSplice Administration client application: a. Enter User Name = Admin and password = changethis i. You will be required to change the password immediately after you log in. b. The Domain will always be DataSplice since you are logging in to the Administrative client. c. DataSplice Server = the server name or IP of the server where DataSplice is installed. i. In the case that you are running the DataSplice Admin Client on the same server that the DataSplice application is installed you can leave the localhost default. ii. If the port was changed in Section D 6.e, then that port number will need to be added to the end of the server address. Ex: localhost:4185 d. Click “Connect”. e. You will get an error prompt “The server license is not valid or has expired”. f. Change the Admin Client password. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 10 4. Requesting new server licenses a. Copy the Server Key and e-mail it to DataSplice Technical Support at support@datasplice.com. Include enough in the e-mail so they know who the client is, which server you are working on (DEV, STAGE, etc). b. DataSplice support will email the server licenses. On Production servers you will receive two licenses: i. One for the activation of the product ii. One for the License count 5. Installing the received Server licenses: a. In the Admin Client, Navigate to the DataSplice Suite. b. Click the Actions Button, select Install License. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 11 c. Copy and paste the Server License key into the Install License box. Click OK. d. The Date Issued will appear indicating the license was successfully added. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 12 e. Repeat steps b and c for the product license key (note: Demo licenses do not need this step). f. The license shows up in the “Product License Information”. g. Now we are ready to configure DataSplice. Section F. Configuring DataSplice5.0 F.1 Configuring the DbPlugin Data Source Setting up the connection profile - After setting up the connection profile DataSplice can query data from the Maximo database. 1. Click on DbPlugin option on the left pane in the DataSplice Administration client. 2. Click on the in Connection Profiles. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 13 3. Enter the following values: a. Name = maximo b. Driver: i. The dropdown will display all of the installed drivers. ii. If using Microsoft SQL server, select it from the list. iii. If using Oracle it will also display here. Note: If you are using an Oracle database, the DataSplice server must have the ODP.NET client installed. The latest version of ODP.NET driver supports database versions 8.1.7 through 11g and is available for download from Oracle's website. c. Database Server: i. If using SQL = Enter the name of the database server. ii. If using Oracle = Enter the following: Server_Name:Listening_Port/DataBase_Name 1. Ex: oracledb_serv:1552/MXdb d. User Name = Enter a database username with a minimum privilege of read only. e. Password = Enter the password for the Username used on step 3. f. Initial Catalog in this example (mx-stage): i. If using SQL = Database name ii. If using Oracle = Leave blank 4. Click save F.2 . Configure the Maximo plugin 1. Click on the Maximo Plug-in. 2. Enter the following values: a. Session Timeout: the time that a session will stay open before disconnecting automatically. b. User Authentication Cache: the time that information regarding a user or group is cached by the server. c. ActualDateOffset: creates a date offset that can help prevent future date errors. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 14 d. JVM DLL Path: the path to the jvm.dll from the 32 bit java installation. i. The value will show up on the dropdown list no need to type it in. ii. If the value does not show either Java is not installed or the class path not set correctly. e. Java class path: this is a pointer to the Maximo MBO’s. i. The Java class path must point to the Maximo MBOs either on the Maximo server or you can copy them to the DS server. ii. The common path for the java class path is: C:\ibm\SMP\maximo\applications\maximo\businessobjects\classes iii. If you are installing against Maximo 7.1: 1. You will need to add the class path for log4j-1.2.13.jar and mail.jar. The common paths for those are: a. C:\ibm\SMP\maximo\applications\maximo\lib\log4j1.2.13.jar b. C:\ibm\SMP\maximo\tools\maximo\internal\mail.jar iv. If you are installing against Maximo 7.5: 1. You will need to add the class path for log4j-1.2.13.jar, mail.jar and icu4j.jar. The common paths for those are: a. C:\ibm\SMP\maximo\applications\maximo\lib\log4j1.2.13.jar b. C:\ibm\SMP\maximo\tools\maximo\internal\mail.jar c. C:\ibm\SMP\maximo\applications\maximo\lib\icu4j.jar v. If you are installing against Maximo 7.5.0.3: 1. You will need to add the class path for log4j-1.2.16.jar, mail.jar and icu4j.jar. The common paths for those are: a. C:\ibm\SMP\maximo\applications\maximo\lib\log4j1.2.16.jar b. C:\ibm\SMP\maximo\tools\maximo\internal\mail.jar c. C:\ibm\SMP\maximo\applications\maximo\lib\icu4j.jar f. Java Memory Megs: the maximum memory available to the Java run time g. Maximo Authentication Domain Name: the name of the authentication domain provided by the plug-in. h. Maximo Server: this is the Maximo server IP or Name, the port that the RMI is listening on and the application server name. i. The format for this entry would be: 1. (Server_name or IP):RMI_port/Application_server_name ii. If the Maximo instance will be clustered it is recommended to set up a JVM just for DS connections. This server should be configured to start first and have the RMI configuration fixed. i. Maximo User Name: the account used to connect to Maximo. j. Maximo User Password: the password for the User name used. k. Authentication Token Provider: the provider of the authentication tokens when using application server authentication. i. If using LDAP please refer to Section H: LDAP Configuration. l. SSO Domain: the domain that houses the user accounts. m. UserNameText: forces the case of the password sent for authentication n. Maximo Database Connection Profile: name of the DbPlugin connection used to query directly from the database rather that going thru the MBO layer. o. Click Save. p. Below an example of a configured Maximo Plug-in: DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 15 q. F.3 Verify 4 OK statuses in the Plugin Status Message box (a service restart may be required to make the database connection. Loading the Out of the Box Configuration files 1. Stop the DataSplice Service. 2. Navigate to: <Installation_Drive>:\DataSplice5.0\Server\Resources\Maximo 7.5 Storage\v4.0 DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 16 3. Copy the Configuration files which are the three folders that you will find in this location. 4. Navigate to: <Installation_Drive>:\DataSplice5.0\Server\Storage and paste the copied folders in this location. 5. Start the DataSplice Service. F.4 Initial Security Configuration 1. Log in to the DataSplice Administrator Client. 2. Click on the Edit accounts Icon. 3. Adding the Maxadmin group to the DataSplice Internal Roles: a. The 3 primary Internal Roles in DataSplice are Maximo Condition Monitoring, Maximo Inventory, and Maximo Work Order. b. Add the Maximo Maxadmin security group as a member of these three Internal Roles: i. Select the internal role from the left column. ii. Change the Domain Name to Maximo. iii. Browse for the MAXADMIN_GROUP. iv. Select the MAXADMIN_GROUP. v. Click the arrow pointing to the right. vi. Save the change. vii. Repeat the steps for all three internal roles. Section G. Testing the Application Installation 1. Run the Remote Client a. Navigate to: <Installation_Drive>:\DataSplice5.0\Clients\Desktop” b. Double click on the RemoteClient.exe application. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 17 c. Log in to the Remote Client: i. Username: Maxadmin ii. Password: <Maxadmin Password> iii. Domain: MAXIMO (Note: Always use MAXIMO all upper case) iv. DataSplice Server: the server name or IP of the server where DataSplice is installed. 1. In the case that you are running the DataSplice Remote Client on the same server that the DataSplice application is installed you can leave the localhost default. v. Click Connect. vi. The application will log you on and will display the views you are authorized to see. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 18 Section H. LDAP Configuration How to configure Maximo and the DataSplice plug-in to utilize LDAP integrated authentication. In this case the application server (Web Logic or WebSphere) is responsible for authenticating users, typically against another backend system such as LDAP, before connections can be established with MAXIMO. 1. Identify the .jsp file for your version of MAXIMO (6 or 7). 2. Copy <DataSplice_Installation_Drive>:\Server\AppServerSecurity\token_mx7.jsp <DataSplice_Installation_Drive>:\Server\AppServerSecurity\token_mx6.jsp into the <Maximo_Instalation_Drive>:\applications\maximo\maximouiweb\webmodule\webclien t\utility\ folder. 3. Rebuild the MXES ear files, restart the MAXIMO server, and redeploy the MAXIMO application. 4. Start the DataSplice server and connect with Administration client. 5. Edit the options for the MAXIMO Integration plug-in and update the following settings: a. MAXIMO User Name/Password - Specify an account that can authenticate with the Application Server. b. Auth Token Provider - Specify the web address for the deployed token_mx7.jsp or token_mx6.jsp file. For instance: http://maxserver:7001/maximo/webclient/utility/token_mx7.jsp 6. Save the settings and restart the DataSplice server. The Maximo Integration Plug-in should now initialize properly and you should be able to log in to DataSplice using the MAXIMO domain. Section I. Desktop Client Installation Prerequisites 1. Install the Microsoft .NET Framework 3.5 or later. This can either be installed through Windows Update, or by downloading the installer from Microsoft's website. 2. If the workstation will be used to provision and maintain handheld devices, install Microsoft ActiveSync (available from Microsoft's website). Local Installation 1. Create the target folder for the clients. Similar to the server installation, it is recommended to create a folder for each instance (C:\Program Files\DataSplice5.0\Dev\). This allows you to run different (and possibly incompatible) version on the various instances as part of development and testing. 2. Copy the Clients folder from the <Installation_Drive>:\DataSplice5.0\Server location to the target location on the clients PC: a. If the user is not an administrator delete the DSAdmin.exe file form the C:\Program Files\DataSplice5.0\Dev\Clients\Desktop\ location. 3. If desired, use the add_admin_shortcut.bat and add_remoteclient_shortcut.bat scripts in the C:\Program Files\DataSplice5.0\Dev\Clients\Desktop\Resources\Scripts\ folder to create shortcuts that will show up in the Programs menu. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 19 Section J. Handheld Device Installation Windows Mobile This used to be called Pocket PC, and is the most commonly used shell for handhelds. The shell is highly optimized for the small form factor of devices, having the menu and toolbar at the bottom of the screen (which is easier to reach with the stylus). Windows CE (Windows Embedded Compact) This is often referred to as Handheld PC. This shell is more similar to desktop windows than Pocket PC, with a task bar at the bottom of the screen and toolbars and menus at the top. This shell is often more difficult to use than Pocket PC, but it has the advantage of supporting displays larger than the typical 240x320 for factor. Installing DataSplice on Handheld Devices The first step is to connect the handheld to a computer using ActiveSync. This will create a Mobile Device entry under My Computer in Windows Explorer. Launching Cab File Installs Most applications are distributed as CAB files that install a package on the device. 1. Copy the desired cab file to any location on the handheld (\Temp\ works well) using Windows Explorer on the desktop. 2. From the handheld, run File Explorer and navigate to the location used above and tap on the cab file. 3. If storage cards are available this will prompt for the desired location to install the files. a. Install system prerequisites into <Device> and DataSplice packages on the storage card. Installing DataSplice 1. Install prerequisites. Depending on the device, these packages may come pre-installed as part of the firmware: a. The necessary cab files to install the prerequisites are grouped in folders based on the target platform. The first step is to determine the platform being used, then you will typically install all the available cab files within the target folder: i. Mobile\CabFiles\PPC5\ - Windows Mobile version 5 and later ii. Mobile\CabFiles\PPC4\ - Windows Mobile/Pocket PC version 4 iii. Mobile\CabFiles\CE5\ - Windows CE.NET version 5 and later b. For each platform the following prerequisites need to be installed: i. Microsoft Compact Framework 3.5 - Installs or updates the Microsoft .NET Compact Framework on the device. Install NETCF3.5.<platform>.cab ii. Microsoft SQL Server Mobile - Provides Mobile SQL Server to support offline installations. Install sqlce.<platform>.cab and sqlce.repl.<platform>.cab c. Cab file Installation - This is the quickest and easiest way to install DataSplice. This cab file supports all platforms and mobile operating systems. i. Install Mobile\CabFiles\RemoteClient-ARM_PPC.cab d. Manual Installation - This supports installing to custom locations, multiple installations, or other modifications to the distribution files if desired: i. Create the target folder on the handheld for the application ii. Copy the contents of the <DataSpliceRoot>\Clients\Mobile\Binaries\ folder to the target. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 20 iii. You will need to manually create shortcuts and place them in \Windows\Start Menu\Programs\ if desired. Section K. Trouble Shooting K.1 Connection Troubleshooting If errors are encountered when connecting to the DataSplice Server, make sure you obtain the exact error message that is displayed. The message in question is very helpful in determining the underlying cause, which is essential to fix the issue. The following error messages indicate issues connecting to the DataSplice server: Invalid server address or name lookup failure: The server name specified could not be resolved as a network address. This typically indicates problems with the DNS configuration or other network connectivity issues. Failed to establish a connection with the server: DataSplice could not open a network connection with the specified server. This can mean the server is not running, or a firewall, etc. is blocking the connection. Authentication timeout!: The authentication process did not succeed in the allowed time period. This can indicate that the backend servers are overloaded, and can also be caused by network connectivity problems. Other error messages mean a connection to the server was established, but a session could not be created for the specified account: The server rejected the connection. Invalid authentication domain: The provided Domain value does not match a configured authentication domain. The server rejected the connection. Authentication failure (or "User ID and password and not valid. Please try again."): The authentication source rejected the provided User Name or Password. The server rejected the connection. The account does not have permission to access any views. Please contact your system administrator: The account authenticated properly, but is not configured to access to views. This typically means that the account is not a member of any roles in DataSplice that provide view permissions. The server rejected the connection. No licenses are available for this user. Please contact your administrator or try again later: All available licenses are in use. The Administration Client can be used to free stale licenses if any appear to be abandoned, or this could be an indication that not enough licenses are available to server the current usage patterns. The server rejected the connection. Failed to load the Maximo Plug-in: This indicates that a Maximo account is trying to authenticate with DataSplice and a connection to the Maximo application server could not be successfully established. Check the plug-in status to identify the underlying error message, and verify that the Maximo services are operational. DataSplice Mobile Computing Software – Abstract Brief DataSplice 414 E. Oak Street Fort Collins, Colorado 80524 21