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