Cisco ICM Interface User s Guide

Transcription

1 WebSphere Voice Response for AIX with DirectTalk Technology Cisco ICM Interface User s Guide Version 4.2 SC

2 Note Before using this information and the product it supports, read the general information under Notices on page 161. Third edition (August 2008) This edition applies to Version 4, Release 2 of IBM WebSphere Voice Response for AIX with DirectTalk Technology (program number 5724-I07), and to all subsequent releases and modifications until otherwise indicated in new editions. Make sure you are using the correct edition for the level of the product. Copyright International Business Machines Corporation 1991, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

3 Contents Figures vii Tables ix About this book xi Who should use this book xi How to use this book xi Terms used in this book xi Following the procedures in this book... xii Typographic conventions xii Accessibility xiii Notes on terminology xiii Where to find more information..... xiv Useful Web sites xiv Making comments on this book..... xiv Chapter 1. Introduction Cisco ICM custom server overview Application development for Cisco ICM...3 State tables Java Chapter 2. Installing and configuring the Cisco ICM custom server Installation prerequisites Installation procedure Configuring your Cisco licenses Running the installation verification test...6 Migration Coexistence SSI and HACMP error handling Configuring for Java dtjenv file default.cff file Deconfiguring Java Chapter 3. Starting the Cisco ICM custom server Starting the Cisco ICM custom server automatically The Cisco ICM simulator Custom server parameters Examples Running multiple instances of the Cisco ICM custom server Service definition file If you have a problem Chapter 4. Application development using state tables Call Routing Interface (CRI) CRI custom server functions for state tables 26 Call_Cleared_Event Delivered_Event Diverted_Event Get_CallID Get_Route Get_ServiceID New_Transaction_Event Originated_Event Route_End_Event Route_Request_Event Set_Call_Variables_Event Set_Instance_Number Set_VRU_Status_Variables Event Data Feed and Call Routing Interface Status Codes Service Control Interface (SCI) Service Control Interface usage overview 42 Expanded Call Context Variables Service Control Interface using state tables 44 SCI custom server functions for state tables 45 Cancel Connect Connect_To_Resource Create_DialogueID Dialogue_Failure_Conf_Send Dialogue_Failure_Event_Send Dialogue_Failure_Event_Recv Event_Report New_Call New_Call_Extended New_Dialogue Register_Variables Release Release_DialogueID Request_Instruction Retrieve_Index_Value Copyright IBM Corp. 1991, 2008 iii

4 Resource_Connected Run_Script_Request Run_Script_Result Run_Script_Result_Extended Chapter 5. Application development using Java Service Control Interface (SCI) Service Control Interface usage overview 75 Expanded Call Context Variables Service Control Interface using Java...76 The Java CTICisco Application Programming Interface CTICiscoReturn object CTICiscoCallVars object SCI custom server functions for Java cancel connect connecttoresource dialoguefailureconfsend dialoguefailureeventrecv dialoguefailureeventsend eventreport newcall registervariables release requestinstruction resourceconnected runscriptrequest runscriptresult waitforevent Chapter 6. Service Control Interface scenarios and examples Call #1) Arriving call not under ICM script control (for a state table application) Call #2) Arriving call already under ICM script control (for a Java application) Call #3) Arriving call already under ICM script control, and the script requested to be run does not exist (for a state table application) Call #4) Arriving call not under ICM script control, and a Cancel request is received (for a Java application) Call #5) Arriving call not under ICM script control, and a Failed Cancel request is received (for a state table application) Call #6) Arriving call not under ICM script control and receives a Release Request (for a Java application) Call #7) TimeOut during dialog creation (for a state table application) Call #8) Arriving call not under ICM script control, and a Cancel request is received, VRU instructed to transfer call (for a Java application) Service Control Interface codes Call Cleared causes Label types Status codes Status codes for a Java application Event codes Unsolicited event codes Appendix A. Application launch file Appendix B. Cisco ICM simulator Set_Simulation_Variables Set_Simulation_Variables Parameters Appendix C. Cisco ICM custom server error messages Appendix D. Format of status and trace data Status data Trace data Printable ICM messages Notices Trademarks Glossary List of WebSphere Voice Response and associated documentation WebSphere Voice Response software IBM hardware for use with WebSphere Voice Response Withdrawn from marketing but still supported WebSphere Voice Response related products 192 WebSphere Voice Server for Multiplatforms Unified Messaging for WebSphere Voice Response iv Cisco ICM Interface User s Guide

5 AIX and the IBM pseries computer HACMP SS Integrated Services Digital Network Bellcore Specifications for ADSI Telephones 195 Index Contents v

6 vi Cisco ICM Interface User s Guide

7 Figures 1. WebSphere Voice Response and ICM 1 2. Routing calls using ICM Arriving call not under ICM script control (for a state table application) Arriving call already under ICM script control (for a Java application) Arriving call already under ICM script control, and the script requested to be run does not exist (for a state table application) Call #4) Arriving call not under ICM script control, and a Cancel request is received (for a Java application) Arriving call not under ICM control and Failed Cancel request received (for a state table application) Arriving call not under ICM script control and receives a Release Request (for a Java application) TimeOut during dialog creation (for a state table application) Arriving call not under ICM script control, Cancel request received, VRU transfers call (for a Java application) Copyright IBM Corp. 1991, 2008 vii

8 viii Cisco ICM Interface User s Guide

9 Tables 1. ICM application interfaces to voice response systems Format of the service definition file Sample definition file Summary of the custom server functions Event Data Feed and Call Routing Interface Status Codes get methods for the CTICiscoReturn object get and set methods for the CTICiscoCallVars object Call Cleared causes Label types Status codes Status codes for a Java application Event codes Unsolicited event codes Application launch file used in the installation verification test Format of an application launch file Cisco ICM custom server error messages Copyright IBM Corp. 1991, 2008 ix

10 x Cisco ICM Interface User s Guide

11 About this book This book explains how to install and use the Cisco ICM custom server and how to link your IBM WebSphere Voice Response for AIX with DirectTalk Technology system to the Cisco ICM. GeoTel is now owned by Cisco Systems, and is called Cisco Intelligent Contact Management software (Cisco ICM). WebSphere Voice Response for AIX supports Cisco ICM version 1.0 through 7.0. If you want information about later versions, contact your IBM representative. For information on Cisco ICM functions that are supported by WebSphere Voice Response, see Cisco ICM custom server overview on page 1. Who should use this book This book is written for the person who wants to install the Cisco ICM custom server, configure it, and write applications that use the custom server functions. You should be familiar with basic programming concepts, and how to use WebSphere Voice Response state tables and custom servers. How to use this book Read this book to become familiar with the Cisco ICM custom server and its functions. The appendixes contain reference information. Terms used in this book GeoTel custom server is now called Cisco ICM custom server. In this book, the name GeoTel custom server is only used where a direct reference to the interface is being made, for example a desciption of an example window. Throughout this book, Cisco Intelligent Contact Management (Cisco ICM) is referred to as the ICM. Reference is made to trunks and trunk groups. These are terms that are used by Cisco in their specifications. Copyright IBM Corp. 1991, 2008 xi

12 terms used in this book A trunk is translated to a WebSphere Voice Response channel, which is similar to a single telephone line. A trunk group is similar to a WebSphere Voice Response channel group. It represents a collection of channels that are all using the same signaling process. This book uses the Cisco terminology. Following the procedures in this book Typographic conventions The procedures assume that you are already familiar with using a mouse and window environment and that you know how to use the common actions, such as Save, to work with information. If you are new to WebSphere Voice Response, refer to the WebSphere Voice Response for AIX: User Interface Guide, which tells you how to log on and log off, and use the WebSphere Voice Response windows well. This book uses the following typographic conventions: boldface Identifies an item that is in a WebSphere Voice Response window. The item might be a keyword, an action, a field label, or a pushbutton. Whenever one of the steps in a procedure includes a word in boldface, look in the window for an item that is labeled with that word. boldface italics Are used for emphasis. Take extra care wherever you see bold italics. italics Identify one of the following: v New terms that describe WebSphere Voice Response components or concepts. A term that is printed in italics is usually followed by its definition. v Parameters for which you supply the actual names or values. v References to other books. monospace Identifies one of the following: v Text that you type in an AIX window. Because AIX is case sensitive, ensure that you type the uppercase and lowercase characters exactly as shown. v Names of files and directories (path names). xii Cisco ICM Interface User s Guide

13 accessibility Accessibility WebSphere Voice Response for AIX is a voice application enabler. The applications that are developed to run on WebSphere Voice Response provide telephone access to business data and services. In this way, WebSphere Voice Response provides accessibility for people who cannot access the data and services by using regular Web pages or traditional graphic interfaces. These telephone user interfaces are fully accessible to people who are blind or have low vision and, if speech recognition is used, to people with mobility impairments or limited hand use. Speech recognition capability can be provided by products such as IBM WebSphere Voice Server. In addition, support for users of Telephony Devices for the Deaf (TDD) is provided as part of the WebSphere Voice Response product. With WebSphere Voice Response you can perform many application development and system administration tasks with a text editor or line commands these are accessible if you use a screen reader product to interface with them. Also, the default settings of the WebSphere Voice Response graphical user interface can be changed to produce large fonts and high contrast colors. Details of how to use these accessibility features can be found in the WebSphere Voice Response for AIX: User Interface Guide. Alternatively, application development can be done with Java or VoiceXML development tools that are supplied by IBM and third parties. You can also use a screen-reader product to access the WebSphere Voice Response publications in HTML format (for details of their availability refer to List of WebSphere Voice Response and associated documentation on page 191 at the back of this book). Notes on terminology v A glossary of commonly-used terms is at the end of this book. v The full product name of WebSphere Voice Response for AIX with DirectTalk Technology is generally abbreviated in this book to WebSphere Voice Response. v The term pseries is generically used in this book to refer both to PCI-based RS/6000 computers and to appropriate models of the System p5 and pseries ranges. (Consult your IBM representative for details of models that are supported for use with WebSphere Voice Response.) RS/6000 computers with an MCA bus are not supported. v The IBM Quad Digital Trunk Telephony PCI Adapter is generally referred to in this book by its abbreviation DTTA. This adapter is a replacement for the IBM ARTIC960RxD Quad Digital Trunk PCI Adapter, which is generally referred to by the abbreviation DTXA. v References made to the VoiceXML 2.1 specification are intended to include VoiceXML 2.0 unless otherwise specified. About this book xiii

14 where to find more information Where to find more information The information provided in the WebSphere Voice Response library will help you complete WebSphere Voice Response tasks more quickly. A complete list of the available books and where you can obtain them is shown in List of WebSphere Voice Response and associated documentation on page 191. Useful Web sites The following Web sites are useful sources of information about WebSphere Voice Response and related products: IBM WebSphere voice products Select the Products link on the Pervasive Computing Software home page at IBM WebSphere developerworks resources (including WebSphere Voice products) VoiceXML Version 2.0 and 2.1 specifications CCXML Version 1.0 specification CallPath For more information on CallPath products go to the Genesys Web site at Making comments on this book If you especially like or dislike anything about this book, feel free to send us your comments. You can comment on what you regard as specific errors or omissions, and on the accuracy, organization, subject matter, or completeness of this book. Please limit your comments to the information that is in this book and to the way in which the information is presented. Speak to your IBM representative if you have suggestions about the product itself. When you send us comments, you grant to IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. You can get your comments to us quickly by sending an to idrcf@hursley.ibm.com. Alternatively, you can mail your comments to: User Technologies IBM United Kingdom Laboratories, xiv Cisco ICM Interface User s Guide

15 making comments on this book Mail Point 095, Hursley Park, Winchester, Hampshire, SO21 2JN, United Kingdom Please ensure that you include the book title, order number, and edition date. About this book xv

16 making comments on this book xvi Cisco ICM Interface User s Guide

17 Chapter 1. Introduction The Cisco ICM custom server is an integrated component of WebSphere Voice Response for AIX. It allows you to use the ICM over a TCP/IP link (see Figure 1.) The ICM allows you to create an organization-wide virtual call center and provide improved call distribution performance. For more information about the ICM, see Cisco s Web pages at Call router Voice processing Cisco ICM TCP/IP link pseries WebSphere Voice Response Cisco ICM custom server Figure 1. WebSphere Voice Response and ICM This chapter gives you a short summary of the Cisco ICM custom server. The following chapters tell you about installing this component, checking the installation, and writing applications to use the Cisco ICM custom server. Cisco ICM custom server overview The Cisco ICM custom server enables a WebSphere Voice Response system to communicate with an ICM over a TCP/IP link. The ICM gathers information about the state of the trunks on the WebSphere Voice Response system and about the calls that are processed. The ICM coordinates the delivery of voice and data to a targeted answering resource across the organization, where the resource might be an Interactive Voice Response (IVR) or a call center agent. Copyright IBM Corp. 1991,

18 Cisco ICM custom server overview Using network-provided data, caller-entered digits, and information obtained from a customer-profile database, the ICM determines who is calling and why. Real-time information is also gathered by the ICM from the call center systems to track the resources available to meet the customer s needs. This combination of data is processed through user-defined routing scripts that show a company s business rules. This process enables the ICM to direct each call and related data to the optimal resource anywhere in the organization. This data can also be used to create historical reports of inbound calls, outbound calls, abandoned calls, and the services that have been used. Figure 2 Shows how ICM could route calls to the correct agents in an organization. Transferring funds WebSphere Voice Response with Cisco ICM custom server Opening account French-speaking enquiry Investing $50,000 WebSphere Voice Resopnse Cisco ICM routing Financial services expert Call center supervisor Financial services expert French-speaking agent Figure 2. Routing calls using ICM The ICM provides five application interfaces that can be used to interface with voice response systems. Table 1 on page 3 shows what these interfaces are, the services that they provide, and their compatibility with WebSphere Voice Response. 2 Cisco ICM Interface User s Guide

19 Cisco ICM custom server overview Table 1. ICM application interfaces to voice response systems Application interface name Event data feed interface (EDFI) Description of function Provides a means for the voice response system to send status information to the ICM for call routing and monitoring purposes. Poll data feed Provides the same information to the ICM as the event data feed interface does, but the real-time monitoring information is limited. Compatible with WebSphere Voice Response? Compatible with state table applications? Yes Yes No No, because the event data feed interface is used. No Compatible with Java applications? No Call routing interface (CRI) Time synchronization interface Service control interface (SCI) This is offered as an interface for voice response platforms that cannot implement the event data feed interface. The voice response system uses this interface to request routing instructions for calls that must be transferred. This interface can be used to synchronize the voice response system clock with the ICM clock to ensure that times are reported consistently. This interface is used to allow the ICM to provide call-handling instructions to a voice response system. Yes Yes No No No No Yes Yes Yes The Cisco ICM custom server can be used in a standard PSTN telephony network environment or in a Voice over IP environment and is compatible with Cisco s IPCC architecture. Application development for Cisco ICM The custom server supports input from one application programming environment at a time. It must be started in either Java or state table mode. Chapter 1. Introduction 3

20 application development for Cisco ICM State tables A state table specifies the logic of the interaction of an application with callers and contains a sequence of instructions (states) that perform the activities of a voice application. Each state defines an action to be performed. The result of each action controls which state is executed next. A state table can call a custom server, invoke other state tables, and use prompts and voice segments. The Cisco ICM application calls functions from the Cisco ICM custom server. Java WebSphere Voice Response detects an incoming call and requests routing instructions from the ICM. The ICM responds with routing instructions for the calling application. A possible sequence of Cisco ICM custom server functions in a routing dialog is: v v v Get_CallID Route_Request_Event Get_Route v Route_End_Event The ability to call a custom server within an application greatly expands the capabilities of WebSphere Voice Response. Java applications provide the same functionality as state tables do, but unlike the proprietary state table programming environment, Java is an open interface. Java is also very easy to integrate with other systems so call control can be fully integrated with Cisco ICM. WebSphere Voice Response needs to be running an instance of the Java and VoiceXML environment to provide the interface between the Java application and WebSphere Voice Response. With WebSphere Voice Response for AIX, you can use Java as a wrapper layer to integrate VoiceXML dialogs with existing state table applications. For example, if you have state tables that provide standard dialogs or that invoke custom servers to access databases, you can continue to use these with your new VoiceXML applications. A possible sequence of Java methods in a Service Control Interface dialog is: v newcall v v v waitforevent runscriptrequest runscriptresult 4 Cisco ICM Interface User s Guide

21 Chapter 2. Installing and configuring the Cisco ICM custom server The Cisco ICM custom server component is supplied as an installp image. You use the smitty command of the System Management Interface Tool (SMIT) to install it. When installing the Cisco ICM custom server, refer to the Installing the WebSphere Voice Response software procedure in the WebSphere Voice Response for AIX: Installation guide. When you have installed the component, import the custom server and state table. Run the installation verification test to ensure that the installation was successful. Installation prerequisites Before you start installing the software: v Ensure that you have a copy of WebSphere Voice Response for AIX: Installation. v Ensure that you have enough disk space for the components that you are installing. Use the procedure described in Ensuring you have enough space for the new software in WebSphere Voice Response for AIX: Installation. Installation procedure Install the package 1. Following the instructions that are given in Installing the WebSphere Voice Response software in WebSphere Voice Response for AIX: Installation, use SMIT to install the dirtalk.geotel package. Start WebSphere Voice Response 2. Start WebSphere Voice Response, and log in to the user account that you use for WebSphere Voice Response administration. Import the Cisco ICM custom server 3. From the WebSphere Voice Response Welcome window, click Applications to open the Applications window, then click Application > Import > Replace > File to import /usr/lpp/dirtalk/sw/geotel/geotel.imp. When the import is complete, click View > Refresh to see the imported objects. The Cisco ICM custom server is put into the Cisco application. Copyright IBM Corp. 1991,

22 configuring Cisco licenses Configuring your Cisco licenses The Cisco ICM custom server is license-enabled software. Before you can use the software, you must use the IBM License Use Management product to enroll and to distribute your licenses. For instructions, see WebSphere Voice Response for AIX: Installation. Running the installation verification test Run the installation verification test to check whether the Cisco ICM custom server is correctly installed. This test uses a state table to run all the custom server functions that are in simulation mode. The system uses the application launch file to test the state table see Appendix A, Application launch file, on page 133. Before you run the installation verification test, ensure that WebSphere Voice Response is running with telephony hardware enabled, and that the System Monitor channels are idle. Run the installation verification test as follows: 1. Change to the GeoTel_dir directory by entering, on a command line: cd $CUR_DIR/ca/GeoTel_dir 2. Start the test by entering: geotest 3. A series of messages from the Cisco ICM state table is written to the terminal. 4. When you see the message "Exiting state table", end the test by keying CTRL+C. 5. View the GeoTel.log file in the $OAM_LOG_PATH directory. Toward the end of the file is the message: All nn tests have completed successfully. where n is a digit 0 through 9. The value of n can vary with the version of the software. The installation verification test has completed. You are now ready to customize the Cisco ICM custom server. To do this see Custom server parameters on page 12. If you want to test whether the custom server works with WebSphere Voice Response channel groups and WebSphere Voice Response channel numbering, repeat the above instructions except for Step 2, where you must enter: geotest -c 6 Cisco ICM Interface User s Guide

23 installation verification test Otherwise, physical WebSphere Voice Response trunk and channel numbers are used. Migration The process for migration to this version of the custom server is the same as the process for installation, except that the custom server must be stopped from the Custom Server Manager window before installation. You should backup the service definition file before you migrate to a new version of WebSphere Voice Response or of the Cisco ICM custom server. An automatic migration tool to move from a state table application to a Java application is not provided as part of the WebSphere Voice Response product. Coexistence This upgrade to the Cisco ICM custom server replaces the old custom server and cannot coexist with a previous version. In a cluster of WebSphere Voice Response clients, which are not part of a single system image (SSI) cluster, each client can have a different version of the custom server under the following conditions: v Each client must have a peripheral gateway (PG). v The PG has the correct software for the version of the Cisco ICM custom server that the client is running. In a cluster of WebSphere Voice Response clients that are part of an SSI cluster, the clients all run the same version of the Cisco ICM custom server. Only one Cisco ICM custom server can be installed and run at any one time on a single WebSphere Voice Response for AIX machine. SSI and HACMP error handling If a DB2 or NFS failure occur, WebSphere Voice Response client machines handle an SSI cluster in the same way as they handle an SSI cluster that is running HACMP. This section relates only to the Cisco ICM custom server, not to the application that might be accessing this custom server (the application developer is responsible for this.) The developer is also responsible for the handling of error conditions that occur in the application that are related to DB2 and NFS failures. If either a DB2 or an NFS failure occurs where an IBM WebSphere Voice Response for AIX client is operating in an SSI cluster, the custom server Chapter 2. Installing and configuring the Cisco ICM custom server 7

24 SSI and HACMP error handling continues to function normally if the executable is not paged out. In this condition, the operation is unpredictable and the custom server might fail. If it fails, the custom server must be restarted. When the Cisco ICM custom server informs the ICM of any change in VRU status it does not refer to the WebSphere Voice Response run status. Therefore, it is best that for WebSphere Voice Response clients that are running in an SSI environment that has the Cisco component running, the System Response during Server outage configuration is set to Busy-out all telephony channels. If an outage occurs, all channels are quiesced, and the Cisco ICM custom server reports the condition to the ICM. The ICM, therefore, no longer routes calls to that VRU if the ICM is configured so that it does not route calls to that VRU (for example, all calls in this VRU might come from external callers), this configuration can be set to the user s choices. Such a use for the configuration must be thought about when the network configuration is being designed. Configuring for Java dtjenv file To configure Java for access to the Cisco ICM custom server, you need to edit the dtjenv file and the configuration file default.cff. The dtjenv file is used to initialize local environment variables in the Java environment. The default.cff file contains definitions of all your nodes, and all your applications, and is imported into the configuration database, config.cfd. Full information on editing the default.cff file can be found in WebSphere Voice Response for AIX: Developing Java applications. This section gives information only about things that need to be specifically configured to use the Cisco ICM custom server with Java. Note: If you have DTBE installed, you will need to edit the dtjenv file to initialize local environment variables. If you have VRBE_XML installed, you will not need to edit the dtjenv file. The dtjenv file is in the following directory /usr/lpp/dirtalk/dtbe/native/ aix/dtjenv. The dtjenv file contains a comment: # # Don t change anything below this line # Directly above this commented text, you must type: export DTJ_CLASSPATH=$DTJ_CLASSPATH:${DTBE_HOME:-/var/dirTalk/DTBE}/server/ibmcticisco.jar 8 Cisco ICM Interface User s Guide

25 configuring for Java This line will configure the file for use with a Java application. default.cff file The CTIService provides information on a plug-in factory for Computer Telephony Integration services. To configure a service for access to the Cisco ICM, add the following to the default.cff file: CTIService=CiscoICM Enabled=yes CTIClass=com.ibm.telephony.wvr.ctiplugins.cisco.CTICiscoFactory InitServiceString=xxxx ; where xxxx is equal to the port number specified after the J parameter (information about this parameter can be found in Custom server parameters on page 12.) However, defining InitServiceString is optional: v If a port number is defined after the J parameter (for example J6969) then the InitServiceString is not optional and should be InitServiceString=6969. v If the J parameter is used without a port, the default port number (7253) will be used and InitServiceString does not need to be defined. To define the voice response node for the custom server, add the following line to the node section of the default.cff file: CTIService=CiscoICM,default This must be defined for the voice response node on which the custom server is installed. Deconfiguring Java To deconfigure Java: 1. Remove the line of text that was added to the file dtjenv (see dtjenv file on page 8.) 2. Remove the CTIService statements from the file default.cff (see default.cff file. ) 3. Edit the dtjenv file so that ibmcticisco.jar is referenced at the end of the Java CLASSPATH. To do this, find the line that begins with the text: export CLASSPATH= and add :${DTJ_HOME}/server/ibmcticisco.jar to the end of the line. This step is necessary because the Java configuration database file (config.cfd) will have had new classes from ibmcticisco.jar Chapter 2. Installing and configuring the Cisco ICM custom server 9

26 deconfiguring Java added as a result of configuring the CTIService for CiscoICM. These remain in config.cfd until the next time the configuration database file is rebuilt. 10 Cisco ICM Interface User s Guide

27 Chapter 3. Starting the Cisco ICM custom server Note: In this chapter, where a specific window is being referred to, the name GeoTel custom server is used (instead of Cisco ICM custom server) as this still appears on the product windows. To start the Cisco ICM custom server from the WebSphere Voice Response Welcome Window: 1. Click Operations > Custom Server Manager. 2. Click Run Status of the GeoTel custom server. 3. Click Start. The run status changes to ACTIVE. A process ID is filled in. When the Cisco ICM custom server is started: v The configuration parameters are verified. v The service definition file is loaded and verified. v The connection with the ICM is made. If the Cisco ICM custom server cannot make the connection, it waits for a specified number of seconds, then tries again. v A snapshot of the state of the trunks and services that are available on WebSphere Voice Response is sent to the ICM. If any errors occur during the initialization of the Cisco ICM custom server, the initialization ends and error messages are written to the WebSphere Voice Response error log. If the connection to the ICM is broken, an error is logged and the Cisco ICM custom server tries to reconnect to the ICM. When the connection is broken, a status code is returned to any application that is using the Cisco ICM custom server. When the ICM is reconnected, a snapshot of the state of the trunks and services is sent to the ICM, and an information message is logged. Starting the Cisco ICM custom server automatically To start the Cisco ICM custom server whenever the system is restarted: 1. Click Operations > Custom Server Manager. 2. Click IPL Status of the GeoTel custom server. 3. Click AUTOEXEC. Copyright IBM Corp. 1991,

28 Cisco ICM simulator The Cisco ICM simulator By using the Cisco ICM simulator you can test your Cisco ICM custom server and state tables when the server is not connected to an ICM. Details of the simulator are in Appendix B, Cisco ICM simulator, on page 135. Custom server parameters For WebSphere Voice Response to communicate correctly with the ICM, you must set some command line parameters for the Cisco ICM custom server. The default is for the custom server to start in state table mode. Use the following parameters to customize the behavior of the custom sever: -A <application launch file> Defines the name of an application launch file, which is used when state tables are tested. See Appendix A, Application launch file, on page B <index number> Defines the range of dialogue IDs for use by each VRU so that the dialogue IDs that are used are unique across all VRUs in a VRU/VRU PG pair. index number is an Integer in the range 1 through 200 that must be unique across all VRUs in a VRU/VRU PG pair. This Integer is used to calculate the range of dialogue IDs that each VRU uses; this range is ((<index number> * ) +1) through ((<index number> + 1) * ). -c Specifies that WebSphere Voice Response channel groups and logical channel numbers are to be used for reporting data that relates to telephony traffic to the ICM. If this parameter is not specified, WebSphere Voice Response physical card numbers and physical channel numbers are used when reporting telephony traffic to the ICM. Note: If the -J parameter is used, -c does not need to be specified as channel groups and logical channel numbers will be used for reporting data to the ICM by default. -d <debug level> Defines whether to run the custom server in debug mode. The following values for debug level can be specified: 1 or blank Prints the contents of messages that flow between the custom server and the ICM. 2 Prints the following: v The data that is printed when -d1 is specified 12 Cisco ICM Interface User s Guide

29 custom server parameters v The contents of messages that flow between the processes v The names of the procedures that are run 3 Prints the following: v The data that is printed when -d2 is specified v The contents of many of the variables Debug information is written to the GeoTel.Log file. -e <seconds> Indicates that trunk group status messages should be sent every <seconds> seconds. The time interval must be in the range seconds; the default value is 60 seconds. Applying this parameter modifies the behavior of the trunk group status message, such that trunks are considered out of service if they are busy, in addition to when they are actually out of service (blocked or unavailable). It also allows the use of the parameter to modify the frequency at which this check is made. This parameter should be used in environments where trunk availability data is critical to the performance of the platform, and where it is not possible to achieve the same results using data on the Cisco ICM platform. -f <service definition file name> Defines the name of the service definition file that is described in Service definition file on page 19. -g <parameter definition file> The fully qualified name of the parameter definition that you are using as the configuration parameters for the custom server. See Running multiple instances of the Cisco ICM custom server on page 17 for more information. -h <host machine name> Defines the host (TCP/IP) name of the machine to which the Cisco ICM simulator is to connect. It is stated as a name that is listed in the /etc/hosts file, or as an IP address in dotted-quad notation. For example, if the Cisco ICM custom server is on a machine called leo, specify the parameter as -hleo. -I Controls the debug informational messages that print to the GeoTel.Log file. If this flag is provided on the command line or in the properties window, these messages are printed. If the flag is not provided, the messages are not printed. This parameter is useful because it provides a level of debug that does not need such large file sizes or use as much disk space as the -d flag does. This flag performs this function only on Service Control Interface messages (that is, with the -U parameter selected). Chapter 3. Starting the Cisco ICM custom server 13

30 custom server parameters -J <port number> Instructs the custom server to start in Java mode. If you need to change the port number of the socket connection to Java, specify a number after the -J parameter. This number must match the InitServiceString in the Java configuration file. If no port number is specified, a default port number (7253) is used (and InitServiceString will not need to be defined.) For further information see Configuring for Java on page 8. Note: If the custom server is started in Java mode, it cannot be used with state table applications, and vice versa. -K Indicates that the VRU supports the event data feed interface. -L Indicates that the VRU supports the Call Routing Interface. -l <log file name> Defines the name of the log file into which status and trace data is written. The default name is $OAM_LOG_PATH/GeoTel.Log. When the simulator is running in stand-alone mode, the default name is $OAM_LOG_PATH/GeoTel.Simulator.Log. The format of the status and trace data is described in Appendix D, Format of status and trace data, on page 153. Each time the custom server is started, data is appended to the log file. When the size of the log file reaches bytes, it is renamed by appending a date stamp to its name. -n <number of instances> The number of instances of the Cisco ICM custom server that you want to run. Possible values are 1 to 5 inclusive. See Running multiple instances of the Cisco ICM custom server on page 17 for more information. -p <port number> Defines the TCP/IP port number that is to be used to communicate with the ICM. The port number parameter is not required if the -s parameter is specified. If the -s and -p parameters are both specified, -p is used. -s <service name> Defines the name of the service that is held in the /etc/services file. It is used to determine the port number that is to be used to communicate with the ICM. -T <test setup> Defines how a test system is set up. To test the Cisco ICM custom server when it is not connected to an ICM, you can use this parameter to set up a test system. The test system can be set up either to run the Cisco ICM simulator as an additional process of the custom server, or 14 Cisco ICM Interface User s Guide

31 custom server parameters to run the Cisco ICM simulator as a stand-alone process on a different machine. See Appendix B, Cisco ICM simulator, on page 135. The values for test setup can be: 1 or blank To run the simulator as an additional process in the custom server. 2 To run the simulator in stand-alone mode. If it is run on a second machine, the Cisco executable must be installed on the second machine. -t <connection timeout> Defines how long, in seconds, the custom server can try to connect to the ICM before the custom server is stopped. If this parameter is omitted, the custom server tries to connect until it succeeds, or is stopped. -U Indicates the VRU supports the Service Control Interface. This parameter is ignored if the ICM is at a version that is lower than 4. -V Indicates that the VRU supports the run script feature. This feature is available only if the -U parameter is selected. -W Indicates that the VRU supports the connect instruction to retarget calls. This is available only if the -U parameter is selected. -X Indicates that the VRU supports the release call operation. This is available only if the -U parameter is selected. -Y Indicates that the VRU supports the cancel request operation. This is available only if the -U parameter is selected. -Z Indicates that the VRU supports the blind transfer feature. -z <time zone delta> Defines the existing local time difference, in seconds, from UTC time (coordinated universal time). If this parameter is not specified, the system time zone delta is used. Examples In the following examples, where you are asked to enter a character string, you can type it on the command line while in the $CUR_DIR/GeoTel_dir directory for the GeoTel custom server (the GeoTel custom server is opened from the Custom Server Manager window.) 1. To run the Cisco ICM custom server so that it communicates with an ICM on host , use: v port v A service definition called service.def v The EDFI and CRI interfaces (enabled) Chapter 3. Starting the Cisco ICM custom server 15

32 custom server parameters and enter the following: GeoTel -K -h p fservice.def 2. To run the Cisco ICM custom server so that it communicates with an ICM on host leo, and writes status data into my.log, use: v Service dt6000 v A service definition called service.def v The EDFI and CRI interfaces (enabled) and enter the following: GeoTel -K -sdt6000 -fservice.def -lmy.log -hleo 3. To run the Cisco ICM custom server so that it communicates with an ICM on port 7001, and writes status data into the default log file, use: v A service definition called service.def v Channel groups and logical channel numbers for reporting telephony traffic v The EDFI and CRI interfaces (enabled) and enter the following : GeoTel -K -p7001 -fservice.def -c 4. To test a state table using the Cisco ICM simulator running on port 9000, use: v A service definition file called service.def v The EDFI and CRI interfaces (enabled) and enter the following: GeoTel -K -p9000 -fservice.def -T Note: You must enter this example from the command line because you need to be able to enter input to the Cisco ICM simulator. 5. To run the Cisco ICM custom server so that it communicates with host , and has the Run_Script, Connect, Release and Cancel operations enabled, use: v Port 7001 v A service definition file called service.def v The SCI interface (but not the EDFI or CRI interfaces enabled) and enter the following: GeoTel -p7001 -h fservice.def -U -V -W -X -Y 6. To run the Cisco ICM custom server so that it communicates with host and has the Run_Script operation supported, use: v Port 7001 v A service definition file called service.def 16 Cisco ICM Interface User s Guide

33 custom server parameters v The SCI and EDFI interfaces enabled and enter the following: GeoTel -p7001 -h fservice.def -K -U -V 7. To test a state table using the Cisco ICM simulator running on port 8000, that supports the Connect and Cancel operations, use: v A service definition file called service.def v The SCI and EDFI interfaces enabled and enter the following: GeoTel -p8000 -fservice.def -T -K -U -W -Y Note: You must enter this example from the command line because you need to be able to enter input to the Cisco ICM simulator. 8. To run the Cisco ICM custom server in Java mode so that it communicates with host and has the Run_Script operation supported, use: v Port 7001 v A service definition file called service.def v The SCI interface enabled and enter the following: GeoTel -p7001 -h fservice.def -U -V -J Running multiple instances of the Cisco ICM custom server In some scenarios, you may want to run multiple instances of the Cisco ICM custom server on the same WebSphere Voice Response system. In order to do this, the system should be started with only the n and g parameters as described in Custom server parameters on page 12. The parameter definition file then contains all the attributes that are required for the different custom server instances. Note that in a multi-instance environment only a single instance may be configured to use the Java and VoiceXML environment multiple Java instances are not supported. The format of this file is similar to the attributes that you specify on the command line, however the instance number must also be specified for each parameter. For example, to specify the debug level for an instance, the file would list d <instance number> <debug level>. Below is an example definition file: -d11 -d20 -d31 -f1/home/dirtalk/current_dir/ca/geotel_dir/services1.def -f2/home/dirtalk/current_dir/ca/geotel_dir/services2.def -f3/home/dirtalk/current_dir/ca/geotel_dir/services3.def -B11 -B22 -B33 -K1 Chapter 3. Starting the Cisco ICM custom server 17

34 custom server parameters -K2 -K3 -U1 -U2 -U3 -V1 -V2 -V3 -W1 -W2 -W3 -X1 -X2 -X3 -Y1 -Y2 -Y3 -Z1 -Z2 -Z3 18 Cisco ICM Interface User s Guide

35 service definition file Service definition file The service definition file is used to define which services are available. A service is a particular type of processing that a caller requires. For example, in a software company s call center, a caller with a question about installing software would be directed to the Technical Support service; a caller wanting to purchase software might be directed to the Sales service. Assign a unique identifier for each service that you provide for your callers. Each call that is received or started by WebSphere Voice Response is linked to a service. You assign a static identifier, a Service ID, to each service. The ICM uses the Service ID to distinguish one service that is on the WebSphere Voice Response system from another. The IDs are configured in the ICM central database and should remain constant across WebSphere Voice Response restarts. The ICM uses information about services to make call routing decisions. The ICM also provides this information in real time monitor screens and historical reports. The format of the service definition file is as follows. The fields are separated by one or more blanks. Table 2. Format of the service definition file Field name Value Data type Max size ServiceID The number of the service STRING 9 ServiceAvailable "Y" indicates the service is available. "N" or "n" indicate that the service is not available StateTable The name of the state table that runs the service, ended by a blank STRING 1 STRING 15 ServiceName Descriptive name of the service STRING 39 Chapter 3. Starting the Cisco ICM custom server 19

36 service definition file Table 3 shows the service definition file that is used in the installation verification test. Table 3. Sample definition file * Service Definition File * ServiceID ServiceAvailable StateTable ServiceName 1 Y None General Info 2 Y GeoTel1 Problem Support 3 N GeoTel2 Not Available 4 Y GeoTel3 Account Enquiry * The next entry is used to test outgoing calls 3001 Y S2 Number to Call The service definition file is verified when the custom server is started or when a request is made to obtain a ServiceID. During verification of the file the following checks are made: v If a record contains a non numerical value in the ServiceID field, it is ignored. For example, in Table 3, records with "*" in the ServiceID field are ignored. v If the contents of the ServiceAvailable field is not "Y", the service is handled as being unavailable. v The ServiceName field value for a service must be unique in the file. An error is reported if the field value is not unique. v The StateTable field value for a service must be unique within the file. An error is reported if the field value is not unique. v The ServiceID field value for a service must be unique within the file. An error is reported if the field value is not unique. v There must be at least one available service. An error is reported if no service is available. v Blank lines are not permitted in the service definition file. If a blank line is included in the file, it will cause a duplicated record error. Each time a request is made to obtain a ServiceID, if the file has been changed, it is reloaded and verified again. If an error is found during an attempt to reload the file, reloading is ended and an error is logged. The Cisco ICM custom server continues to operate with the previous version of the file. Any errors that are in the service definition file must be corrected before the Cisco ICM custom server can be restarted. 20 Cisco ICM Interface User s Guide