REM Installation Guide
KANA Response Version 7.5.2
November 2004
REM Installation Guide All contents of this KANA documentation are copyright © 2001- 2004 by KANA and represent the Proprietary and Confidential Information of KANA. All Rights Reserved. © 2001- 2004 KANA Software, Inc. Conditions: This software and documentation is provided solely pursuant to the terms of an agreement between the user and KANA (the “Agreement”) and any use in violation of, or not pursuant to any such Agreement shall be deemed copyright infringement and a violation of KANA's rights in the software and documentation and the user consents to KANA's obtaining of injunctive relief precluding any further such use. KANA assumes no responsibility for any damage that may occur either directly or indirectly, or any consequential damages that may result from the use of this documentation or any KANA software product except as expressly provided in the Agreement, any use hereunder is on an as-is basis, without warranty of any kind, including without limitation the warranties of merchantability, fitness for a particular purpose, and non-infringement. Use, duplication, or disclosure by licensee is subject to restrictions as set forth in the KANA license Agreement. Information contained in this document is subject to change without notice and does not represent a commitment on the part of KANA. The software described in this document is furnished under a license Agreement or nondisclosure Agreement. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose other than the purchaser’s personal use without the written permission of KANA. This document contains proprietary information of KANA Software, Inc. The contents are exempt from disclosure to the public under the Freedom of Information Act 35, U.S.C. 552 (6)(4) and unlawful disclosure thereof is a violation of the Trade Secrets Act, 18 U.S.C. 1905. Public disclosure of any information contained herein shall not be made without prior written permission of KANA. Unless specifically noted, all addresses, data, characters and persons referenced herein, and all examples involving names of companies and products, are fictitious examples and are designed solely to illustrate the use of KANA and its components. KANA is a registered trademark of KANA. KANA Software, the KANA logo, KANA Commerce Analytics, KANA Connect, KANA eCRM Architecture, KANA Knowledge, KANA Marketing, KANA Marketing Analytics, KANA Marketing Automation, KANA Response, KANA Response Conduit, KANA Response CTI Conduit, KANA Response I-Mail, KANA Service, KANA Service Analytics, KANA Service Conduit, KANA Service CTI Conduits, and KANA Studio are trademarks of KANA. All other trademarks are properties of their respective holders. If you find errors or problems with this documentation, please notify KANA. KANA does not guarantee that this document is error-free.
KANA Software, Inc. 181 Constitution Drive Menlo Park, CA 94025 www.kana.com Part number: 153-DOC-752-EN
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 REM Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Upgrading REM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Install REM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Install Response Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Install Database Client Software, If Necessary . . . . . . . . . . . . . . . . 11 Run the REM Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Configuring REM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 REM Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Starting REM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Stopping REM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Uninstalling REM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Remove Schema Objects (optional) . . . . . . . . . . . . . . . . . . . . . . . . 18 Uninstall REM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
REM Installation Guide
i
Contents
ii
REM Installation Guide
Preface Purpose The REM Installation Guide describes how to install the REM (Response Event Mechanism) SDK.
Audience This book is intended for: • System Administrators who are charged with creating a REM development environment. • Engineers who develop solutions using REM. For more information. See the REM SDK Guide for REM API usage
instructions.
Organization REM Installation Guide is organized as follows: Section
Description
Introduction
Brief overview of REM.
System Requirements
Hardware and software requirements.
Install REM
Installation instructions.
Configuring REM
Configuration instructions.
REM Installation Guide
3
Preface
Section
Description
REM Operation
Starting and stopping REM.
Troubleshooting
Troubleshooting suggestions.
Typographical Conventions This document uses the following typographical conventions: Convention
Usage
Bold
File names and URLs
Input
User input and system output
Italic
Emphasis and book titles
Arrow ( >)
Identifies the path of menu commands used in a procedure (File > Save, for example)
Other Product Documentation In addition to this manual, the KANA Response documentation set includes various printed or online documentation collections and manuals. Refer to the Documentation Listing section in the online Release Notes for a complete listing. Available formats
Technical documentation for this product is available in: • Portable Document Format (PDF) • Online help Note: You need Adobe Acrobat Reader to read PDF documents. This
product is available free from Adobe at the following location: http://www.adobe.com/products/acrobat/readstep.html
Other Sources of Information You might need information that is not contained in the printed or online documentation, or you might have questions that are not related to a particular product. Following are some additional resources for you.
4
REM Installation Guide
Preface
Company news
To learn more about KANA products, services, and company news, visit our Web site at www.kana.com.
Technical Support
To contact KANA Technical Support: • Visit support.kana.com • Call (866) 753–KANA • Write
[email protected]
REM Installation Guide
5
Preface
6
REM Installation Guide
REM Installation In this guide
This guide has the following sections: Section
REM Installation Guide
Page
Introduction
8
System Requirements
9
Upgrading REM
10
Install REM
11
Configuring REM
14
REM Operation
17
Uninstalling REM
18
Troubleshooting
19
7
Introduction
Introduction KANA REM is a component in a distributed system that can be accessed remotely from customer’s programs. The REM server is a component that runs as a Windows service and monitors a KANA Response server partition. The REM server generates events that notify subscribers of activity on that Response partition. REM can have multiple subscribers. All subscribers will receive the events as a stream of XML elements. The customer’s program can access the KANA REM API remotely. KANA REM is implemented using Java RMI (Remote Method Invocation). KANA provides the customer with an SDK that implements this API.
8
REM Installation Guide
System Requirements
System Requirements See the REM Release Notes for hardware and software requirements.
REM Installation Guide
9
Upgrading REM
Upgrading REM If upgrading or installing a different version of REM, always uninstall REM first (see Uninstalling REM on page 18). Multiple installations of REM are not allowed
10
REM Installation Guide
Install REM
Install REM Installing REM requires installation of the Response Server, installation of database client software (only if you are using a DB2 database) and running the REM installer.
Install Response Server One of the important prerequisites for REM Installation is the Response Server, which should be installed, up and running. For more information on installing the Response Server refer Response Installation and Configuration Guide
Install Database Client Software, If Necessary DB2 users must install DB2 7.2 database client software on the REM server host to allow connectivity between REM and a DB2 database. Database client software is not required for Microsoft and Oracle users.
Run the REM Installer KANA REM is packaged as InstallShield setup files for Windows.
➤ To install: 1 Go to the directory where you have downloaded the setup files. 2 Run Setup.exe. 3 In the Welcome dialog, click Next. 4 In the Choose Destination Location dialog, enter the appropriate destination directory location and click Next.
The default is “C:\Program Files\KANA\KANA REM”. 5 In the Select Program Folder dialog, enter the appropriate program folder and click Next.
REM Installation Guide
11
Run the REM Installer
The default is KANA. 6 When prompted for SMTP, EmailAddr, and REMHost, enter the
following values: SMTP - Your network local SMTP mail server. EmailAddr - The administrative email address you want to designate as the recipient of REM email notifications. REMHost - The hostname or IP address of the host this instance of REM is being installed on. 7 Click Next. 8 Choose a database type and click Next. 9 When prompted for DBName, DBServer, and DBPort, enter the
following values: DBName - Enter the name of the Response partition database that you selected in the previous step. DBServer - Enter the hostname or IP address of the Response partition database server. DBPort - Enter the socket ID of the port to the database. A default will be offered. Change it only if necessary. 10 Click Next. 11 When prompted for DBUser, Password, and Schema, enter the
following values: DBUser - Enter the database user name for the Response partition database. Password - Enter the password for this user. Schema (DB2 only) - Enter the KANA Response database schema. Only DB2 users are required to enter a value. Microsoft and Oracle users should leave this field blank. 12 Click Next. 13 In the KANA Response Information dialog, enter the following:
Host Name - Enter the hostname or IP address of the Response host/ node that services the partition on which REM will report events
12
REM Installation Guide
Run the REM Installer
Host Port - A default will be offered. Change it only if necessary. 14 Click Next. 15 In the Heartbeat Values dialog, change the default values if necessary and click Next. 16 Choose a REM startup type and click Next. If you want REM to start
automatically when the REM host is rebooted, choose the “Automatically start” option. 17 In the Start Copying Files dialog, click Next.
When the installation is finished, you will notice that two shortcuts have been placed in the Programs > KANA menu: Start KANA REM and Stop KANA REM. There will also be new entries in the registry, HKEY_LOCAL_MACHINE\SOFTWARE\KANA\KANA REM\ and HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Kan a REM\.
REM Installation Guide
13
Configuring REM
Configuring REM Before you can run KANA REM, you must configure it. KANA REM is configured using an ASCII properties file named REM.properties. This file is located in the KANA REM program directory. For changes to go into effect while KANA REM is running, you must stop and restart KANA REM. See REM Operation on page 17 for instructions. Below is a summary of fields found inside the properties file. Modify only the fields listed below. Most of the fields relating to databases should not be changed unless instructed by KANA Professional Services.
14
Field
Description
Smtp_List
A list of SMTP servers that REM can use to send email notification to an administrator.
Admin_Email
The email address of the recipient for REM notifications. Set by the REM installer
App_Name
The name used in the notifications for this instance of REM.
From_Email
The address to be used in the from field of REM email notifications. Set by the REM installer
Rmi_Hostname
The host that this instance of REM is on. This is used for the REM API.
Rmi_Port
This is the port on which the REM API will communicate with remote clients.
Heartbeat_Interval
The interval between tests REM makes on the Response server to determine whether it is still running. Set by the REM installer
Kana_host
The hostname (or IP address) of the Response partition on which REM is producing events. Set by the REM installer.
Kana_port
The port on the Response host used by REM for the heartbeat test.
Connection_timeout
The time to wait before declaring no response from the Response server. Set by the REM installer
REM Installation Guide
Configuring REM
REM Installation Guide
Field
Description
Mode
The logging mode of the REM service. The following are the mode values and their effect: 0 – minimum information. Send data to the logfile specified by the LogFile entry in this properties file. 1 – minimum information. Send data to STDOUT 2 – Detailed information. Send data to STDOUT 3 – Detailed information. Send data to the logfile specified by the LogFile entry in this properties file. Set by the REM installer.
LogFile
Names the file that REM uses to save its logging data. Set by the REM installer.
dbUsername
Name of the database user on the Response database used by this instance of REM. Set by the REM installer.
dbPassword
KANA Response database password. Set by the REM installer.
dbType
KANA Response database type: 2 – Microsoft SQL 4 – Oracle 9 -- DB2 Set by the REM installer.
dbName
KANA Response database instance name. Set by the REM installer.
dbServer
KANA Response database server name. Set by the REM installer.
dbPort
KANA Response database server port number. Set by the REM installer.
dbSchema
KANA Response database schema. Used by DB2 only.
dbSQL_flag_master
SQL statement to enable event reads from REM table. Not for general use. This is primarily for diagnostics or extension.
dbSQL_master_incoming
SQL statement to retrieve REM table data. Not for general use. This is primarily for diagnostics or extension.
15
Configuring REM
16
Field
Description
dbSQL_delete
SQL statement to delete processed REM table data. Not for general use. This is primarily for diagnostics or extension.
Cleanup_Sleep_Time
Period in minutes for the deletion of REM specific database table entries. Only pertains to processed records.
Max_Error
Maximum number of database connection errors before quitting.
Empty_Sleep_Time
Sleep time (in milliseconds) when REM table is empty.
Poll_Sleep_Time
Sleep time (in milliseconds) for polling REM table.
Subscriber_Maxerror
Maximum number of allowable communication errors before unsubscribing a subscriber.
Tcp_Queue_Size
Internal queue size of TCP subscribers measured in number of events.
Http_Queue_SizeI
Internal queue size of HTTP subscribers measured in number of events.
File_Queue_SizeI
Internal queue size of FILE subscribers measured in number of events.
Main_Queue_size
Internal queue size of main queue for handling events measured in number of events.
REM Installation Guide
REM Operation
REM Operation Starting REM Note: Before attempting to run REM, you MUST configure its properties
file first. See Configuring REM on page 14. The Windows Service KANA REM will appear in the Services Control Panel. After proper configuration, KANA REM can be started in two different ways,- from the Control Panel or from the shortcut.
➤ To start from the Control Panel: 1 From the Windows Start menu, go to Settings > Control Panel > Services. 2 Select the KANA REM Service. 3 Click Start.
➤ To start from the Windows shortcut: 1 From the Windows Start menu, go to Programs > KANA. 2 Select Start KANA REM.
Upon successful startup, an email is sent to the administrator specified in the Admin_Email field of the REM.properties file.
Stopping REM REM can be stopped either with the Windows Service Control Panel or by clicking the Stop KANA REM shortcut found in the Start > Programs > KANA menu. Upon successful shutdown, an email is sent to the administrator specified in the Admin_Email field of the REM.properties file.
REM Installation Guide
17
Uninstalling REM
Uninstalling REM To uninstall REM, you can first run a script to remove schema objects from the database and then uninstall REM.
Remove Schema Objects (optional) If there are instances where the REM service was not shut down properly, run the following SQL scripts before uninstalling REM to ensure all REM schema objects are removed:
Database
Script
Oracle
\sql\CleanREM752_Oracle.sql
SQL Server
\sql\CleanREM752_SQL.sql
DB2
\sql\CleanREM752_DB2.sql
Uninstall REM Use Control Panel > Add/Remove Programs to uninstall REM.
18
REM Installation Guide
Troubleshooting
Troubleshooting Make sure that the settings in the REM.properties file are correct. Subscribers using the TCP or HTTP protocols must conform to the following REM protocol definitions: HTTP - The HTTP subscriber will receive XML event messages via HTTP encoded “xml” key value pairs conforming to HTTP/1.0 standards. TCP - The TCP protocol is established once the REM opens a TCP socket connection to the remote TCP subscriber. XML messages will be sent to the TCP subscriber in 8-bit ASCII character streams. Preceding each individual XML message will be 2 bytes representing the length of the XML event message.
REM Installation Guide
19
Troubleshooting
20
REM Installation Guide